IDL Help for Goddard Utilities
Overview
This page was created by the IDL library routine
make_html_help
(from version v5_5_5 of
idlutils). For more information on this routine,
refer to the IDL Online Help Navigator or type:
IDL> ? make_html_help
at the IDL command line prompt.
This file is based on version v5_5_5 of idlutils.
Last modified: Thu Jul 19 16:19:25 2012.
List of Routines
- AD2XY : Compute X and Y from native coordinates and a FITS astrometry structure
- ADSTRING : Return RA and Dec as character string(s) in sexigesimal format.
- ADXY : Use a FITS header to convert astronomical to pixel coordinates
- AIRTOVAC : Convert air wavelengths to vacuum wavelengths
- AITOFF : Convert longitude, latitude to X,Y using an AITOFF projection.
- AITOFF_GRID : Produce an overlay of latitude and longitude lines over a plot or image
- ALTAZ2HADEC : Convert Horizon (Alt-Az) coordinates to Hour Angle and Declination.
- AL_LEGEND : Create an annotation legend for a plot.
- APER : Compute concentric aperture photometry (adapted from DAOPHOT)
- ARCBAR : Draw an arc bar on an image showing the astronomical plate scale
- ARROWS : To display "weathervane" directional arrows on an astronomical image
- ASINH : Return the inverse hyperbolic sine of the argument
- ASPECT :
- ASTDISP : Print astronomical and pixel coordinates in a standard format
- ASTRO : Interactive utility for precession and coordinate conversion.
- ASTROLIB : Add the non-standard system variables used by the IDL Astronomy Library
- AUTOHIST : Draw a histogram using automatic bin-sizing.
- AVG : Return the average value of an array, or 1 dimension of an array
- BARYVEL : Calculates heliocentric and barycentric velocity components of Earth.
- BITGET :
- BIWEIGHT_MEAN : Calculate the center and dispersion (like mean and sigma) of a
- BLINK : To allow the user to alternatively examine two or more windows within
- BLKSHIFT : Shift a block of data to a new position in a file (possibly overlapping)
- BOOST_ARRAY : Append one array onto a destination array
- BOXAVE : Box-average a 1 or 2 dimensional array.
- BPRECESS : Precess positions from J2000.0 (FK5) to B1950.0 (FK4)
- BREAK_PATH() : Breaks up a path string into its component directories.
- BSORT : Function to sort data into ascending order, like a simple bubble sort.
- CALZ_UNRED : Deredden a galaxy spectrum using the Calzetti et al. (2000) recipe
- CCM_UNRED : Deredden a flux vector using the CCM 1989 parameterization
- CENTERTLB :
- CGAXIS :
- CGCOLORFILL :
- CGCOLOR[1] :
- CGCOLOR[2] :
- CGCOLOR[3] :
- CGCONTOUR :
- CGCONTROL :
- CGDEFAULTCOLOR :
- CGDEFCHARSIZE :
- CGDISPLAY :
- CGERASE :
- CGPICKFILE :
- CGPLOT :
- CGPLOTS :
- CGPS2PDF :
- CGQUERY :
- CGSET :
- CGSHOW :
- CGSNAPSHOT :
- CGTEXT :
- CGWINDOW[1] :
- CGWINDOW[2] :
- CGWINDOW_GETDEFS :
- CGWINDOW_SETDEFS :
- CHECKSUM32 : To compute the 32bit checksum of an array (ones-complement arithmetic)
- CHECK_FITS : Check that keywords in a FITS header array match the associated data
- CIC : Interpolate an irregularly sampled field using Cloud in Cell method
- CIRRANGE : To force an angle into the range 0 <= ang < 360.
- CLEANPLOT : Reset all plotting system variables (!P,!X,!Y,!Z) to their default values
- CNTRD : Compute the centroid of a star using a derivative search
- COLOR24 :
- COLORSAREIDENTICAL :
- COMPARE_STRUCT : Compare all matching tag names and return differences
- CONCAT_DIR() : To concatenate directory and file names for current OS.
- CONS_DEC : Obtain the X and Y coordinates of a line of constant declination
- CONS_RA : Obtain the X and Y coordinates of a line of constant right ascension
- CONVERT_TO_TYPE :
- CONVOLVE : Convolution of an image with a Point Spread Function (PSF)
- COPY_STRUCT : Copy all fields with matching tag names from one structure to another
- COPY_STRUCT_INX : Copy matching tags & specified indices from one structure to another
- CORREL_IMAGES : Compute the 2-D cross-correlation function of two images
- CORREL_OPTIMIZE : Find the optimal (x,y) pixel offset of image_B relative to image_A
- CORRMAT_ANALYZE : Find the optimal (x,y) offset to maximize correlation of 2 images
- COSMO_PARAM : Derive full set of cosmological density parameters from a partial set
- COYOTEGRAPHIC :
- CO_ABERRATION : Calculate changes to Ra and Dec due to "the effect of aberration",
- CO_NUTATE : Calculate changes in RA and Dec due to nutation of the Earth's rotation
- CO_REFRACT() : Calculate correction to altitude due to atmospheric refraction.
- CREATE_STRUCT : Create an IDL structure from a list of tag names and dimensions
- CR_REJECT : General, iterative cosmic ray rejection using two or more input images.
- CSPLINE : Function to evaluate a natural cubic spline at specified data points
- CT2LST : To convert from Local Civil Time to Local Mean Sidereal Time.
- CURS : Selects an X windows cursor shape
- CURVAL : Cursor controlled display of image intensities and astronomical coords
- DAOERF : Calulates the intensity, and derivatives, of a 2-d Gaussian PSF
- DAO_VALUE : Returns the value of a DAOPHOT point-spread function at a set of points.
- DATE : Convert day-of-year to a DD-MMM-YYYY string
- DATE_CONV : Procedure to perform conversion of dates to one of three possible formats.
- DAYCNV : Converts Julian dates to Gregorian calendar dates
- DBBUILD : Build a database by appending new values for every item.
- DBCIRCLE : Find sources in a database within specified radius of specified center
- DBCLOSE : procedure to close a data base file
- DBCOMPARE : Display two entries in an IDL database side by side in a column format
- DBCREATE : Create a new data base (.dbf), index (.dbx) or description (.dbh) file
- DBDELETE : Deletes specified entries from data base
- DBEDIT : Interactively edit specified fields in an IDL database.
- DBEDIT_BASIC : Subroutine of DBEDIT_BASIC to edit a database on a dumb terminal.
- DBEXT : Extract values of up to 12 items from an IDL database
- DBEXT_DBF : Subroutine of DBEXT to extract values of up to 18 items from a database
- DBEXT_IND : routine to read a indexed item values from index file
- DBFIND() : Search data base for entries with specified characteristics
- DBFIND_ENTRY : Subroutine of DBFIND to perform an entry number search
- DBFIND_SORT : Subroutine of DBFIND to perform a search using sorted values
- DBFPARSE : Parse the search string supplied to DBFIND. Not a standalone routine
- DBGET : Find entry numbers which contain specified values of a given item.
- DBHELP : List available databases or items in the currently open database
- DBINDEX : Procedure to create index file for data base
- DBINDEX_BLK : Subroutine of DBINDEX to create associated variable of correct datatype
- DBMATCH : Find the entry number in a database for each element of item values
- DBOPEN : Routine to open an IDL database
- DBPRINT : Procedure to print specified items from a list of database entries
- DBPUT : Procedure to place a new value for a specified item into
- DBRD : procedure to read an entry from a data base file or from
- DBSEARCH : Subroutine of DBFIND() to search a vector for specified values
- DBSORT : Routine to sort list of entries in data base
- DBTARGET : Find sources in a database within specified radius of specified target
- DBTITLE : function to create title line for routine dbprint
- DBUPDATE : Update columns of data in a database -- inverse of DBEXT
- DBVAL : procedure to extract value(s) of the specified item from
- DBWRT : procedure to update or add a new entry to a data base
- DBXPUT : routine to replace value of an item in a data base entry
- DBXVAL : Quickly return a value of the specified item number
- DB_ENT2EXT : Convert a database entry to external (IEEE) data format
- DB_ENT2HOST : Converts a database entry from external data format to host format.
- DB_INFO : Function to obtain information on opened data base file(s)
- DB_ITEM : Returns the item numbers and other info. for an item name.
- DB_ITEM_INFO : routine to return information on selected item(s) in the opened
- DB_OR : Combine two vectors of entry numbers, removing duplicate values.
- DB_TITLES : Print database name and title. Called by DBHELP
- DECOMPOSEDCOLOR :
- DELVARX : Delete up to 10 variables for memory management (can call from routines)
- DEREDD : Deredden stellar Stromgren parameters given for a value of E(b-y)
- DETABIFY : Replaces tabs in character strings with appropriate number of spaces
- DIST_CIRCLE : Form a square array where each value is its distance to a given center.
- DIST_ELLIPSE : Create a mask array useful for elliptical aperture photemetry
- ECI2GEO : Convert Earth-centered inertial coordinates to geographic spherical coords
- EQ2HOR : Convert celestial (ra-dec) coords to local horizon coords (alt-az).
- EQPOLE : Convert RA and Dec to X,Y using an equal-area polar projection.
- EQPOLE_GRID : Produce an equal area polar projection grid overlay
- ERROR_MESSAGE :
- EULER : Transform between Galactic, celestial, and ecliptic coordinates.
- EXPAND_TILDE() : Expand tilde in UNIX directory names
- EXTAST : Extract ASTrometry parameters from a FITS image header.
- EXTGRP : Extract the group parameter information out of SXREAD output
- EXTRAP : This procedure fills in the ends of a one-dimensional array from
- FACTOR : Find prime factors of a given number.
- FDECOMP : Routine to decompose file name(s) for any operating system.
- FILTER_IMAGE : Identical to MEDIAN or SMOOTH but handle edges and allow iterations.
- FIND : Find positive brightness perturbations (i.e stars) in an image
- FINDPRO : Find all locations of a procedure in the IDL !PATH
- FIND_ALL_DIR() : Finds all directories under a specified directory.
- FIND_WITH_DEF() : Searches for files with a default path and extension.
- FITEXY : Best straight-line fit to data with errors in both coordinates
- FITSDIR : Display selected FITS keywords from the headers of FITS files.
- FITSRGB_TO_TIFF : Combine separate red, green, and blue FITS images into TIFF format
- FITS_ADD_CHECKSUM : Add or update the CHECKSUM and DATASUM keywords in a FITS header
- FITS_ASCII_ENCODE() : Encode an unsigned longword as an ASCII string to insert in a FITS header
- FITS_CD_FIX : Update obsolete representations of the CD matrix in a FITS header
- FITS_CLOSE :
- FITS_HELP : To print a summary of the primary data units and extensions in a
- FITS_INFO : Provide information about the contents of a FITS file
- FITS_OPEN : Opens a FITS (Flexible Image Transport System) data file.
- FITS_READ : To read a FITS file.
- FITS_TEST_CHECKSUM() : Verify the values of the CHECKSUM and DATASUM keywords in a FITS header
- FITS_WRITE : To write a FITS primary data unit or extension.
- FIXPS :
- FLEGENDRE : Compute the first M terms in a Legendre polynomial expansion.
- FLUX2MAG : Convert from flux (ergs/s/cm^2/A) to magnitudes.
- FM_UNRED : Deredden a flux vector using the Fitzpatrick (1999) parameterization
- FORPRINT : Print a set of vectors by looping over each index value.
- FPUFIX :
- FREBIN : Shrink or expand the size of an array an arbitary amount using interpolation
- FSC_BASE_FILENAME :
- FSC_DROPLIST :
- FSC_FIELD :
- FSC_FILESELECT :
- FSC_PLOTWINDOW :
- FSC_PSCONFIG__DEFINE :
- FSC_PS_SETUP__DEFINE :
- FTAB_DELROW : Delete rows of data from a FITS ASCII or binary table extension
- FTAB_EXT : Routine to extract columns from a FITS (binary or ASCII) table.
- FTAB_HELP : Describe the columns of a FITS binary or ASCII table extension(s).
- FTAB_PRINT : Print the contents of a FITS (binary or ASCII) table extension.
- FTADDCOL : Routine to add a field to a FITS ASCII table
- FTCREATE : Create a new (blank) FITS ASCII table and header with specified size.
- FTDELCOL : Delete a column of data from a FITS table
- FTDELROW : Delete a row of data from a FITS table
- FTGET : Function to return value(s) from specified column in a FITS ASCII table
- FTHELP : Routine to print a description of a FITS ASCII table extension
- FTHMOD : Procedure to modify header information for a specified field
- FTINFO : Return an informational structure from a FITS ASCII table header.
- FTKEEPROW : Subscripts (and reorders) a FITS table. A companion piece to FTDELROW.
- FTPRINT : Procedure to print specified columns and rows of a FITS table
- FTPUT : Procedure to add or update a field in an FITS ASCII table
- FTSIZE : Procedure to return the size of a FITS ASCII table.
- FTSORT : Sort a FITS ASCII table according to a specified field
- FXADDPAR : Add or modify a parameter in a FITS header array.
- FXBADDCOL : Adds a column to a binary table extension.
- FXBCLOSE : Close a FITS binary table extension opened for read.
- FXBCOLNUM() : Returns a binary table column number.
- FXBCREATE : Open a new binary table at the end of a FITS file.
- FXBDIMEN() : Returns the dimensions for a column in a FITS binary table.
- FXBFIND : Find column keywords in a FITS binary table header.
- FXBFINDLUN() : Find logical unit number UNIT in FXBINTABLE common block.
- FXBFINISH : Close a FITS binary table extension file opened for write.
- FXBGROW : Increase the number of rows in a binary table.
- FXBHEADER() : Returns the header of an open FITS binary table.
- FXBHELP : Prints short description of columns in a FITS binary table.
- FXBHMAKE : Create basic FITS binary table extension (BINTABLE) header.
- FXBINTABLE : Common block FXBINTABLE used by "FXB" routines.
- FXBISOPEN() : Returns true if UNIT points to an open FITS binary table.
- FXBOPEN : Open binary table extension in a disk FITS file for reading or updating
- FXBPARSE : Parse the binary table extension header.
- FXBREAD : Read a data array from a disk FITS binary table file.
- FXBREADM : Read multiple columns/rows from a disk FITS binary table file.
- FXBSTATE() : Returns the state of a FITS binary table.
- FXBTDIM() : Parse TDIM-like kwywords.
- FXBTFORM : Returns information about FITS binary table columns.
- FXBWRITE : Write a binary data array to a disk FITS binary table file.
- FXBWRITM : Write multiple columns/rows to a disk FITS binary table file.
- FXFINDEND : Find the end of a FITS file.
- FXHCLEAN : Removes required keywords from FITS header.
- FXHMAKE : Create a basic FITS header array.
- FXHMODIFY : Modify a FITS header in a file on disk.
- FXHREAD : Reads a FITS header from an opened disk file.
- FXMOVE : Skip to a specified extension number or name in a FITS file
- FXPAR() : Obtain the value of a parameter in a FITS header.
- FXPARPOS() : Finds position to insert record into FITS header.
- FXPOSIT : Return the unit number of a FITS file positioned at specified extension
- FXREAD : Read basic FITS files.
- FXWRITE : Write a disk FITS file.
- F_FORMAT : Choose a nice floating format for displaying an array of REAL data.
- GALAGE : Determine the age of a galaxy given its redshift and a formation redshift.
- GAL_FLAT : Transforms the image of a galaxy so that the galaxy appears face-on
- GAL_UVW : Calculate the Galactic space velocity (U,V,W) of star
- GAUSSIAN : Compute the 1-d Gaussian function and optionally the derivative
- GCIRC : Computes rigorous great circle arc distances.
- GCNTRD : Compute the stellar centroid by Gaussian fits to marginal X,Y, sums
- GEO2ECI : Convert geographic spherical coordinates to Earth-centered inertial coords
- GEO2GEODETIC : Convert from geographic/planetographic to geodetic coordinates
- GEO2MAG() : Convert from geographic to geomagnetic coordinates
- GEODETIC2GEO : Convert from geodetic (or planetodetic) to geographic coordinates
- GETDECOMPOSEDSTATE :
- GETOPT : Convert a string supplied by the user into a valid scalar or vector
- GETPRIMARYSCREENSIZE :
- GETPRO : Search !PATH for a procedure, and copy into user's working directory
- GETPSF : To generate a point-spread function (PSF) from observed stars.
- GETROT : Return the rotation and plate scale of an image from its FITS header
- GETTOK : Retrieve the first part of a (vector) string up to a specified character
- GETWRD : Return the n'th word from a text string.
- GET_COORDS : Converts a string with angular coordinates to floating point values.
- GET_DATE : Return the (current) UTC date in CCYY-MM-DD format for FITS headers
- GET_EQUINOX : Return the equinox value from a FITS header.
- GET_JULDATE : Return the current Julian Date
- GLACTC : Convert between celestial and Galactic (or Supergalactic) coordinates.
- GLACTC_PM : Convert between celestial and Galactic (or Supergalactic) proper
- GROUP : Assign stars with non-overlapping PSF profiles into distinct groups
- GSSSADXY : Converts RA and DEC (J2000) to (X,Y) for an STScI GuideStar image.
- GSSSEXTAST : Extract IDL astrometry structure from a ST Guide Star Survey FITS header
- GSSSXYAD : Convert (X,Y) coordinates in a STScI Guide Star image to RA and Dec
- GSSS_STDAST : Insert the closest tangent projection astrometry into an GSSS Image
- HADEC2ALTAZ : Converts Hour Angle and Declination to Horizon (alt-az) coordinates.
- HASIMAGEMAGICK :
- HASTROM : Transformation of an image to align it with a reference image
- HBOXAVE : Box average an image array and update the FITS header array
- HCONGRID : CONGRID an image and update astrometry in a FITS header
- HEADFITS : Read a FITS (primary or extension) header into a string array.
- HELIO : Compute (low-precision) heliocentric coordinates for the planets.
- HELIO_JD : Convert geocentric (reduced) Julian date to heliocentric Julian date
- HELIO_RV : Return the heliocentric radial velocity of a spectroscopic binary
- HERMITE : To compute Hermite spline interpolation of a tabulated function.
- HEULER : Change the coordinate system of a FITS header or astrometry structure
- HEXTRACT : Extract a subimage from an array and update astrometry in FITS header
- HGREP : Find a substring in a FITS header (or any other string array)
- HISTOGAUSS : Histograms data and overlays it with a Gaussian. Draws the mean, sigma,
- HOR2EQ : Converts local horizon coords (alt-az) of something to equatorial (ra-dec).
- HOST_TO_IEEE : Translate an IDL variable from host to IEEE representation
- HPRECESS : Precess the astrometry in a FITS header to a new equinox
- HPRINT : Display a FITS header (or other string array)
- HREBIN : Expand or contract a FITS image using (F)REBIN and update the header
- HREVERSE : Reverse an image about either dimension and update FITS astrometry
- HROT : Rotate an image and create new FITS header with updated astrometry.
- HROTATE : Apply the IDL ROTATE function and update astrometry in a FITS header
- IEEE_TO_HOST : Translate an IDL variable from IEEE-754 to host representation
- IMAGE_DIMENSIONS :
- IMCONTOUR : Make a contour plot labeled with astronomical coordinates.
- IMDBASE : Find the sources in an IDL database that are located on a given image.
- IMF : Compute an N-component power-law logarithmic initial mass function
- IMLIST : Display pixel values on an image surrounding a specified X,Y center.
- IRAFDIR : Provide a brief description of the IRAF images on a directory
- IRAFRD : Read an IRAF (.imh) file into IDL image and header arrays.
- IRAFWRT : Write IDL data in IRAF (OIF) format (.imh and .pix files).
- ISARRAY : Tests if the argument is an array.
- ISMEUV : Compute the continuum interstellar EUV optical depth
- IS_IEEE_BIG : Determine if the current machine uses IEEE, big-endian numbers.
- JDCNV : Converts Gregorian dates to Julian days
- JPLEPHINTERP : Interpolate position and motion of planetary bodies (JPL Ephemeris)
- JPLEPHREAD : Open and read JPL DE200 or DE405 Ephemeride FITS File
- JPLEPHTEST : Test JPLEPHTEST with JPL test data set
- JPRECESS : Precess astronomical coordinates from B1950 to J2000
- JULDATE : Convert from calendar to Reduced Julian Date
- KSONE : Compute the one-sided Kolmogorov-Smirnov statistic
- KSTWO : Return the two-sided Kolmogorov-Smirnov statistic
- KUIPERONE : Compute the one-sided Kuiper statistic (invariant Kolmogorov-Smirnov)
- KUIPERTWO : Compute the two-sided Kuiper statistic (invariant Kolmogorov-Smirnov)
- LEGEND : Create an annotation legend for a plot.
- LEGENDTEST : Demo program to show capabilities of the legend procedure.
- LINEID_PLOT : Plot spectrum with specified line identifications annotated at the
- LINKEDLIST :
- LINMIX_ERR : Bayesian approach to linear regression with errors in both X and Y
- LINTERP : Linearly interpolate tabulated 1-d data from one grid to a new one.
- LIST_WITH_PATH : Search for files in a specified directory path.
- LSF_ROTATE: : Create a 1-d convolution kernel to broaden a spectrum from a rotating star
- LUMDIST : Calculate luminosity distance (in Mpc) of an object given its redshift
- MAG2FLUX : Convert from magnitudes to flux (ergs/s/cm^2/A).
- MAG2GEO() : Convert from geomagnetic to geographic coordinates
- MAKE_2D : Change from 1-d indexing to 2-d indexing
- MAKE_ASTR : Build an astrometry structure from input parameter values
- MATCH : Routine to match values in two vectors.
- MATCH2 : Routine to cross-match values in two vectors (including non-matches)
- MAX_ENTROPY : Deconvolution of data by Maximum Entropy analysis, given the PSF
- MAX_LIKELIHOOD : Maximum likelihood deconvolution of an image or a spectrum.
- MEANCLIP : Computes an iteratively sigma-clipped mean on a data set
- MEDARR : Compute the median at each pixel across a set of 2-d images
- MEDSMOOTH : Median smoothing of a vector, including points near its ends.
- MINF_BRACKET : Bracket a local minimum of a 1-D function with 3 points,
- MINF_CONJ_GRAD : Find the local minimum of a scalar function using conjugate gradient
- MINF_PARABOLIC : Minimize a function using Brent's method with parabolic interpolation
- MINF_PARABOL_D : Minimize a function using a modified Brent's method with derivatives
- MINMAX : Return a 2 element array giving the minimum and maximum of an array
- MKHDR : Make a minimal primary (or IMAGE extension) FITS header
- MLINMIX_ERR : Bayesian approach to multiple linear regression with errors in X and Y
- MMM : Estimate the sky background in a stellar contaminated field.
- MODFITS : Modify a FITS file by updating the header and/or data array.
- MONTH_CNV : Convert between a month name and the equivalent number
- MOONPOS : To compute the RA and Dec of the Moon at specified Julian date(s).
- MPHASE : Return the illuminated fraction of the Moon at given Julian date(s)
- MRANDOMN : Function to draw NRAND random deviates from a multivariate normal
- MRDFITS : Read all standard FITS data types into arrays or structures.
- MRD_HREAD : Reads a FITS header from an opened disk file or Unix pipe
- MRD_SKIP : Skip a number of bytes from the current location in a file or a pipe
- MRD_STRUCT : Return a structure as defined in the names and values data.
- MULTINOM : SIMULATE MULTINOMIAL RANDOM VARIABLES
- MULTIPLOT : Create multiple plots with simple control over the gaps between plots.
- MWRFITS : Write all standard FITS data types from input arrays or structures.
- NGP : Interpolate an irregularly sampled field using Nearest Grid Point
- NINT : Nearest integer function.
- NSTAR : Simultaneous point spread function fitting (adapted from DAOPHOT)
- NULLTRIM : Trim a string of all characters after and including the first null
- NUTATE : Return the nutation in longitude and obliquity for a given Julian date
- N_BYTES() : To return the total number of bytes in data element
- OBSERVATORY : Return longitude, latitude, altitude & time zones of an observatory
- ONE_ARROW : Draws an arrow labeled with a single character on the current device
- ONE_RAY : Draw a line with a specified starting point, length, and angle
- OPLOTERROR : Over-plot data points with accompanying X or Y error bars.
- ORDINAL : Convert an integer to a correct English ordinal string:
- PARTVELVEC : Plot the velocity vectors of particles at their positions
- PCA : Carry out a Principal Components Analysis (Karhunen-Loeve Transform)
- PENT : Return the information entropy of a time series
- PICKCOLORNAME :
- PIXCOLOR : Assign colors to specified pixel values in a color lookup table
- PIXWT : Circle-rectangle overlap area computation.
- PKFIT : Subroutine of GETPSF to perform a one-star least-squares fit
- PLANCK() : To calculate the Planck function in units of ergs/cm2/s/A
- PLANET_COORDS : Find low or high precision RA and DEC for the planets given a date
- PLOTERROR : Plot data points with accompanying X or Y error bars.
- PLOTHIST : Plot the histogram of an array with the corresponding abcissa.
- PLOTSYM : Define useful plotting symbols not in the standard !PSYM definitions.
- POIDEV : Generate a Poisson random deviate
- POLINT : Interpolate a set of N points by fitting a polynomial of degree N-1
- POLREC : Convert 2-d polar coordinates to rectangular coordinates.
- POLYLEG : Evaluate a Legendre polynomial with specified coefficients.
- POLY_SMOOTH : Apply a least-squares (Savitzky-Golay) polynomial smoothing filter
- POSANG : Computes rigorous position angle of source 2 relative to source 1
- POSITIVITY : Map an image uniquely and smoothly into all positive values.
- PRECESS : Precess coordinates from EQUINOX1 to EQUINOX2.
- PRECESS_CD : Precess the CD (coordinate description) matrix from a FITS header
- PRECESS_XYZ : Precess equatorial geocentric rectangular coordinates.
- PREMAT : Return the precession matrix needed to go from EQUINOX1 to EQUINOX2.
- PRIME : Return an array with the specified number of prime numbers.
- PRINT_STRUCT : Print the tag values of an array of structures in nice column format.
- PROB_KS : Return the significance of the Kolmogoroff-Smirnov statistic
- PROB_KUIPER : Return the significance of the Kuiper statistic
- PROGRAMROOTDIR :
- PSCONFIG :
- PSF_GAUSSIAN : Create a 1-d, 2-d, or 3-d Gaussian with specified FWHM, center
- PSWINDOW :
- PS_BACKGROUND :
- PS_END :
- PS_START :
- PUTAST : Put WCS astrometry parameters into a given FITS header.
- QDCB_GRID : Produce an overlay of latitude and longitude lines over a plot or image
- QGET_STRING : To get a string from the keyboard without echoing it to the screen.
- QSIMP : Integrate using Simpson's rule to specified accuracy.
- QTRAP : Integrate using trapezoidal rule to specified accuracy.
- QUADTERP : Quadratic interpolation of X,Y vectors onto a new X grid
- QUERYDSS : Query the digital sky survey (DSS) on-line at the STSCI (or ESO) server
- QUERYGSC : Query the Guide Star Catalog (GSC V2.3.2) at STScI by position
- QUERYSIMBAD : Query the SIMBAD/NED/Vizier astronomical name resolver to obtain coordinates
- QUERYVIZIER : Query any catalog in the Vizier database by position
- RADEC : To convert RA and Dec from decimal to sexigesimal units.
- RANDOMCHI : GENERATE CHI-SQUARE DISTRIBUTED RANDOM VARIABLES.
- RANDOMDIR : GENERATE DIRICHLET-DISTRIBUTED RANDOM VARIABLES.
- RANDOMGAM : GENERATE GAMMA-DISTRIBUTED RANDOM VARIABLES.
- RANDOMP : Generates an array of random numbers distributed as a power law.
- RANDOMWISH :
- RDFITS_STRUCT : Read an entire FITS file (all extensions) into a single IDL structure.
- RDFLOAT : Quickly read a numeric ASCII data file into IDL floating/double vectors.
- RDPLOT : Like CURSOR but with a full-screen cursor and continuous readout option
- RDPSF : Read the FITS file created by GETPSF in the DAOPHOT sequence
- READCOL : Read a free-format ASCII file with columns of data into IDL vectors
- READFITS : Read a FITS file into IDL data and header variables.
- READFMT : Quickly read a fixed format ASCII data file into IDL variables.
- READ_FMR : Read a journal (ApJ, AJ) machine-readable table into IDL
- READ_KEY : To read a keystroke and return its ASCII equivalent
- RECPOL : Convert 2-d rectangular coordinates to polar coordinates.
- REMCHAR : Remove all appearances of character (char) from string (st)
- REMOVE : Contract a vector or up to 25 vectors by removing specified elements
- REM_DUP : Function to remove duplicate values from a vector.
- REPCHR : Replace all occurrences of one character with another in a text string.
- REPSTR : Replace all occurences of one substring by another.
- RESISTANT_MEAN : Outlier-resistant determination of the mean and standard deviation.
- RINTER : Cubic interpolation of an image at a set of reference points.
- ROBUST_LINEFIT : An outlier-resistant two-variable linear regression.
- ROBUST_POLY_FIT : An outlier-resistant polynomial fit.
- ROBUST_SIGMA : Calculate a resistant estimate of the dispersion of a distribution.
- ROB_CHECKFIT : Used by ROBUST_... routines to determine the quality of a fit and to
- SCALE_VECTOR :
- SELECT_W : Create a non-exclusive widget menu of items
- SETDECOMPOSEDSTATE :
- SETDEFAULTVALUE :
- SIGMA_FILTER : Replace pixels more than a specified pixels deviant from its neighbors
- SIGRANGE() : Selects the most significant data range in an image.
- SIXLIN : Compute linear regression coefficients by six different methods.
- SIXTY() : Converts a decimal number to sexigesimal.
- SKY : Determine the sky level in an image
- SKYADJ_CUBE : Sky adjust the planes of a datacube.
- SPEC_DIR() : Complete a file specification by appending the default disk or directory
- SPHDIST : Angular distance between points on a sphere.
- SRCOR : Correlate the source positions found on two lists.
- STARAST : Compute astrometric solution using positions of 2 or 3 reference stars
- STORE_ARRAY : Insert array INSERT into the array DESTINATION
- STRCOMPRESS2 : Remove blanks around specified characters in a string
- STRN : Convert a number to a string and remove padded blanks.
- STRNUMBER() : Function to determine if a string is a valid numeric value.
- STR_INDEX() : Get indices of a substring (SUBSTR) in string.
- STR_SIZE :
- ST_DISKREAD : Read HST FITS formatted disk files and reconstruct GEIS (STSDAS) files.
- ST_DISK_DATA : Routine to read next header and data array from an HST FITS disk file.
- ST_DISK_GEIS : Routine to construct GEIS files from ST FITS disk files.
- ST_DISK_TABLE : Routine to read FITS table from an ST fits on disk.
- SUBSTAR : Subtract a scaled point spread function at specified star position(s).
- SUNPOS : To compute the RA and Dec of the Sun at a given date.
- SUNSYMBOL : Return the Sun symbol as a subscripted postscript character string
- SXADDHIST : Procedure to add HISTORY (or COMMENT) line(s) to a FITS header
- SXADDPAR : Add or modify a parameter in a FITS header array.
- SXDELPAR : Procedure to delete a keyword parameter(s) from a FITS header
- SXGINFO : Return information on all group parameters in an STSDAS header.
- SXGPAR : Obtain group parameter value in SDAS/FITS file
- SXGREAD : Read group parameters from a Space Telescope STSDAS image file
- SXHCOPY : Copies selected portions of one header to another
- SXHMAKE : Create a basic STSDAS header file from an IDL data array
- SXHREAD : Procedure to read a STSDAS header from disk.
- SXHWRITE : Procedure to write an STSDAS or FITS header to disk as a *.hhh file.
- SXMAKE : Create a basic ST header file from an IDL array prior to writing data.
- SXOPEN : Open a Space Telescope formatted (STSDAS) header file.
- SXPAR : Obtain the value of a parameter in a FITS header
- SXREAD : Read a Space Telescope STSDAS image file
- SXWRITE : Write a group of data and parameters in ST format
- SYMCAT :
- TABINV : To find the effective index of a function value in an ordered vector.
- TABLE_APPEND : Routine to append STSDAS tables to create a single table.
- TABLE_CALC : Adds a new table column from a expression using existing columns
- TABLE_DELETE : Delete specified rows from an STSDAS table
- TABLE_EXT : Routine to extract columns from an STSDAS table
- TABLE_HELP : Procedure to decribe an SDAS table file.
- TABLE_LIST : List the contents of an STSDAS table.
- TABLE_PRINT : Routine to print an stsdas table.
- TABLE_SORT : Procedure to sort an STSDAS table by the specified column
- TAB_ADDCOL : Procedure to add a new column to an existing STSDAS table.
- TAB_COL : Procedure to extract column information from table control block
- TAB_CREATE : Procedure to create a new table file.
- TAB_DEL : Delete specified row(s) from an STSDAS table
- TAB_EXPAND : routine to expand the size of an SDAS table file.
- TAB_FORTOSPP : Procedure to convert a FORTRAN format to an SPP format specfication.
- TAB_MODCOL : Modify column description in a STSDAS table
- TAB_NULL : function to locate null values within a vector of values from
- TAB_NULLROW : Insert null row(s) into a STSDAS table
- TAB_PRINT : Routine to print an stsdas table.
- TAB_PUT : Procedure to place new values into a STSDAS table.
- TAB_READ : Procedure to read an SDAS table file
- TAB_SIZE : Routine to extract the table size from a table control block
- TAB_SORT : Procedure to sort table by the specified column
- TAB_SPPTOFOR : This procedure converts an spp format specification to a normal
- TAB_VAL : Routine to read a column from an SDAS table file
- TAB_WRITE : Routine to write an stsdas table to disk
- TAG_EXIST() : To test whether a tag name exists in a structure.
- TBDELCOL : Delete a column of data from a FITS binary table
- TBDELROW : Delete specified row or rows of data from a FITS binary table
- TBGET : Return value(s) from specified column in a FITS binary table
- TBHELP : Routine to print a description of a FITS binary table header
- TBINFO : Return an informational IDL structure from a FITS binary table header.
- TBPRINT : Procedure to print specified columns & rows of a FITS binary table
- TBSIZE : Procedure to return the size of a FITS binary table.
- TDB2TDT : Relativistic clock corrections due to Earth motion in solar system
- TEN() : Converts a sexigesimal number or string to decimal.
- TENV() : Converts sexigesimal number or string vector to decimal.
- TEXTCLOSE : Close a text outpu file previously opened with TEXTOPEN
- TEXTOPEN : Open a device specified by TEXTOUT with unit !TEXTUNIT
- TICLABELS : Create tic labels for labeling astronomical images.
- TICPOS : Specify distance between tic marks for astronomical coordinate overlays
- TICS : Compute a nice increment between tic marks for astronomical images.
- TIC_ONE : Determine the position of the first tic mark for astronomical images.
- TO_HEX : Translate a non-negative decimal integer to a hexadecimal string
- TRANSFORM_COEFF() : Compute new polynomial coefficients under a linear transformation
- TRAPZD : Compute the nth stage of refinement of an extended trapezoidal rule.
- TSC : Interpolate an irregularly sampled field using a Triangular Shaped Cloud
- TSUM : Trapezoidal summation of the area under a curve.
- TVBOX : Draw a box(es) or rectangle(s) of specified width
- TVCIRCLE : Draw circle(s) of specified radius at specified position(s)
- TVELLIPSE : Draw an ellipse on the current graphics device.
- TVLASER : Prints screen or image array onto a Postscript file or printer.
- TVLIST : Cursor controlled listing of image pixel values in a window.
- T_APER : Driver procedure (for APER) to compute concentric aperture photometry.
- T_FIND : Driver procedure (for FIND) to locate stars in an image.
- T_GETPSF : Driver procedure (for GETPSF) to generate a PSF from isolate stars.
- T_GROUP : Driver procedure (for GROUP) to place stars in non-overlapping groups.
- T_NSTAR : Driver procedure (for NSTAR) for simultaneous PSF fitting.
- T_SUBSTAR : Driver procedure (for SUBSTAR) to subtract scaled PSF values
- UNDEFINE : The purpose of this program is to delete or undefine
- UNZOOM_XY : Converts X, Y position on the image display to the the X,Y position
- UPDATE_DISTORT : Update SIP nonlinear distortion coefficients for a linear transformation
- UVBYBETA : Derive dereddened colors, metallicity, and Teff from Stromgren colors.
- VACTOAIR : Convert vacuum wavelengths to air wavelengths
- VALID_NUM() : Check if a string is a valid number representation.
- VECT : Print a set of numbers as a string with delimiters included
- VSYM : Create "Mongo"-like polygonal plot symbols
- WCSSPH2XY : Convert spherical coordinates to x and y (map) angular coordinates
- WCSXY2SPH : Convert x and y (map) coordinates to spherical coordinates
- WCS_DEMO : Demonstrate the basic capabilities of procedures WCSSPH2XY & WCSXY2SPH
- WCS_GETPOLE : Compute the coordinates of the native pole for a non-polar projection
- WCS_ROTATE : Rotate between standard (e.g. celestial) and native coordinates
- WEBGET() : Use the IDL SOCKET procedure to get data from http servers
- WFPC2_METRIC : Compute the distortion in a WFPC2 image and optionally return coordinates
- WFPC2_READ : Read WFPC2 images in either FITS or STSDAS format into IDL variables.
- WHERENAN() : Find the indices of all big-endian NaN values in an array. OBSOLETE
- WHERE_TAG : Like WHERE but works on structure tag names
- WINDOWAVAILABLE :
- WRITEFITS : Write IDL array and header variables to a disk FITS file.
- XDISPSTR : Display a string array in a text widget with a simple search capability.
- XMEDSKY : Subtract sky from an image as a 1-D function of X
- XY2AD : Compute R.A. and Dec from X and Y and a FITS astrometry structure
- XYAD : Use a FITS header to convert pixel (X,Y) to world coordinates
- XYXY : To use a pair of headers to convert X/Y positions from one frame
- XYZ : Calculate geocentric X,Y, and Z and velocity coordinates of the Sun
- YDN2MD : Convert from year and day number of year to month and day of month.
- YMD2DN : Convert from year, month, day to day number of year.
- ZANG : Determine the angular size of an object as a function of redshift
- ZBRENT : Find the zero of a 1-D function up to specified tolerance.
- ZENPOS : Return the zenith RA and Dec in radians for a given Julian date.
- ZOOM_XY : Converts X, Y position on the image array to the the X,Y position
- ZPARCHECK : Routine to check user parameters to a procedure
Routine Descriptions
AD2XY
NAME: AD2XY PURPOSE: Compute X and Y from native coordinates and a FITS astrometry structure EXPLANATION: If a WCS projection (Calabretta & Greisen 2002, A&A, 395, 1077) is present, then the procedure WCSXY2SPH is used to compute native coordinates. If distortion is present then this is corrected. In all cases, the inverse of the CD matrix is applied and offset from the reference pixel to obtain X and Y. AD2XY is generally meant to be used internal to other procedures. For interactive purposes, use ADXY. CALLING SEQUENCE: AD2XY, a ,d, astr, x, y INPUTS: A - R.A. or longitude in DEGREES, scalar or vector D - Dec. or longitude in DEGREES, scalar or vector ASTR - astrometry structure, output from EXTAST procedure containing: .CD - 2 x 2 array containing the astrometry parameters CD1_1 CD1_2 in DEGREES/PIXEL CD2_1 CD2_2 .CDELT - 2 element vector giving increment at reference point in DEGREES/PIXEL .CRPIX - 2 element vector giving X and Y coordinates of reference pixel (def = NAXIS/2) in FITS convention (first pixel is 1,1) .CRVAL - 2 element vector giving coordinates of the reference pixel in DEGREES .CTYPE - 2 element vector giving projection types .LONGPOLE - scalar longitude of north pole (default = 180) .PV2 - Vector of additional parameter (e.g. PV2_1, PV2_2) needed in some projections .DISTORT - Optional substructure specifying distortion parameters OUTPUTS: X - row position in pixels, scalar or vector Y - column position in pixels, scalar or vector X,Y will be in the standard IDL convention (first pixel is 0), and *not* the FITS convention (first pixel is 1) NOTES: AD2XY tests for presence of WCS coordinates by the presence of a dash in the 5th character position in the value of CTYPE (e.g 'DEC--SIN'). PROCEDURES USED: TAG_EXIST(), WCSSPH2XY REVISION HISTORY: Converted to IDL by B. Boothman, SASC Tech, 4/21/86 Use astrometry structure, W. Landsman Jan. 1994 Do computation correctly in degrees W. Landsman Dec. 1994 Only pass 2 CRVAL values to WCSSPH2XY W. Landsman June 1995 Don't subscript CTYPE W. Landsman August 1995 Understand reversed X,Y (X-Dec, Y-RA) axes, W. Landsman October 1998 Consistent conversion between CROTA and CD matrix W. Landsman October 2000 No special case for tangent projection W. Landsman June 2003 Work for non-WCS coordinate transformations W. Landsman Oct 2004 Use CRVAL reference point for non-WCS transformation W.L. March 2007 Use post V6.0 notation W.L. July 2009
(See $IDLUTILS_DIR/goddard/pro/astrom/ad2xy.pro)
ADSTRING
NAME: ADSTRING PURPOSE: Return RA and Dec as character string(s) in sexigesimal format. EXPLANATION: RA and Dec may be entered as either a 2 element vector or as two separate vectors (or scalars). One can also specify the precision of the declination in digits after the decimal point. CALLING SEQUENCE result = ADSTRING( ra_dec, precision, /TRUNCATE ) or result = ADSTRING( ra,dec,[ precision, /TRUNCATE ] ) or result = ADSTRING( dec, [ PRECISION= ] INPUTS: RA_DEC - 2 element vector giving the Right Ascension and declination in decimal degrees. or RA - Right ascension in decimal degrees, numeric scalar or vector DEC - Declination in decimal degrees, numeric scalar or vector OPTIONAL INPUT: PRECISION - Integer scalar (0-4) giving the number of digits after the decimal of DEClination. The RA is automatically 1 digit more. This parameter may either be the third parameter after RA,DEC or the second parameter after [RA,DEC]. If only DEC is supplied then precision must be supplied as a keyword parameter. If no PRECISION parameter or keyword is passed, a precision of 1 for both RA and DEC is returned to maintain compatibility with past ADSTRING versions. Values of precision larger than 4 will be truncated to 4. If PRECISION is 3 or 4, then RA and Dec should be input as double precision. OPTIONAL INPUT KEYWORD: /TRUNCATE - if set, then the last displayed digit in the output is truncated in precision rather than rounded. This option is useful if ADSTRING() is used to form an official IAU name (see http://vizier.u-strasbg.fr/Dic/iau-spec.htx) with coordinate specification. The IAU name will typically be be created by applying STRCOMPRESS/REMOVE) after the ADSTRING() call, e.g. strcompress( adstring(ra,dec,0,/truncate), /remove) ;IAU format PRECISION = Alternate method of supplying the precision parameter, OUTPUT: RESULT - Character string(s) containing HR,MIN,SEC,DEC,MIN,SEC formatted as ( 2I3,F5.(p+1),2I3,F4.p ) where p is the PRECISION parameter. If only a single scalar is supplied it is converted to a sexigesimal string (2I3,F5.1). EXAMPLE: (1) Display CRVAL coordinates in a FITS header, H IDL> crval = sxpar(h,'CRVAL*') ;Extract 2 element CRVAL vector (degs) IDL> print, adstring(crval) ;Print CRVAL vector sexigesimal format (2) print,adstring(30.42,-1.23,1) ==> ' 02 01 40.80 -01 13 48.0' print,adstring(30.42,+0.23) ==> ' 02 01 40.8 +00 13 48.0' print,adstring(+0.23) ==> '+00 13 48.0' (3) The first two calls in (2) can be combined in a single call using vector input print,adstring([30.42,30.42],[-1.23,0.23], 1) PROCEDURES CALLED: RADEC, SIXTY() REVISION HISTORY: Written W. Landsman June 1988 Addition of variable precision and DEC seconds precision fix. ver. Aug. 1990 [E. Deutsch] Output formatting spiffed up October 1991 [W. Landsman] Remove ZPARCHECK call, accept 1 element vector April 1992 [W. Landsman] Call ROUND() instead of NINT() February 1996 [W. Landsman] Check roundoff past 60s October 1997 [W. Landsman] Work for Precision =4 November 1997 [W. Landsman] Major rewrite to allow vector inputs W. Landsman February 2000 Fix possible error in seconds display when Precision=0 P. Broos/W. Landsman April 2002 Added /TRUNCATE keyword, put leading zeros in seconds display P. Broos/W. Landsman September 2002 Fix declination zero values under vector processing W.Landsman Feb 2004 Fix possible problem in leading zero display W. Landsman June 2004 Assume since V5.4, omit fstring() call W. Landsman April 2006 Fix significant bug when round a declination with -1<dec<0 Add PRECISION keyword W.L. Aug 2008 Use formatting for "+" and "0" W. L. May 2009
(See $IDLUTILS_DIR/goddard/pro/astro/adstring.pro)
ADXY
NAME: ADXY PURPOSE: Use a FITS header to convert astronomical to pixel coordinates EXPLANATION: Use an image header to compute X and Y positions, given the RA and Dec (or longitude, latitude) in decimal degrees. CALLING SEQUENCE: ADXY, HDR ;Prompt for Ra and DEC ADXY, hdr, a, d, x, y, [ /PRINT, ALT= ] INPUTS: HDR - FITS Image header containing astrometry parameters OPTIONAL INPUTS: A - Right ascension in decimal DEGREES, scalar or vector D - Declination in decimal DEGREES, scalar or vector If A and D are not supplied, user will be prompted to supply them in either decimal degrees or HR,MIN,SEC,DEG,MN,SC format. OPTIONAL OUTPUT: X - row position in pixels, same number of elements as A and D Y - column position in pixels X and Y will be in standard IDL convention (first pixel is 0) and not the FITS convention (first pixel is 1). As in FITS an integral value corresponds to the center of a pixel. OPTIONAL KEYWORD INPUT: /PRINT - If this keyword is set and non-zero, then results are displayed at the terminal. ALT - single character 'A' through 'Z' or ' ' specifying an alternate astrometry system present in the FITS header. The default is to use the primary astrometry or ALT = ' '. If /ALT is set, then this is equivalent to ALT = 'A'. See Section 3.3 of Greisen & Calabretta (2002, A&A, 395, 1061) for information about alternate astrometry keywords. OPERATIONAL NOTES: If less than 5 parameters are supplied, or if the /PRINT keyword is set, then the X and Y positions are displayed at the terminal. If the procedure is to be used repeatedly with the same header, then it would be faster to use AD2XY. PROCEDURES CALLED: AD2XY, ADSTRING(), EXTAST, GETOPT(), TEN() REVISION HISTORY: W. Landsman HSTX January, 1988 Use astrometry structure W. Landsman January, 1994 Changed default ADSTRING format W. Landsman September, 1995 Check if latitude/longitude reversed in CTYPE keyword W. L. Feb. 2004 Added ALT keyword W. Landsman September 2004 Work for non-spherical coordinate transformation W. Landsman May 2005 More informative error message if astrometry missing W.L. Feb 2008 Cosmetic updates W.L. July 2011
(See $IDLUTILS_DIR/goddard/pro/astrom/adxy.pro)
AIRTOVAC
NAME: AIRTOVAC PURPOSE: Convert air wavelengths to vacuum wavelengths EXPLANATION: Wavelengths are corrected for the index of refraction of air under standard conditions. Wavelength values below 2000 A will not be altered. Uses relation of Ciddor (1996). CALLING SEQUENCE: AIRTOVAC, WAVE_AIR, [ WAVE_VAC] INPUT/OUTPUT: WAVE_AIR - Wavelength in Angstroms, scalar or vector If this is the only parameter supplied, it will be updated on output to contain double precision vacuum wavelength(s). OPTIONAL OUTPUT: WAVE_VAC - Vacuum wavelength in Angstroms, same number of elements as WAVE_AIR, double precision EXAMPLE: If the air wavelength is W = 6056.125 (a Krypton line), then AIRTOVAC, W yields an vacuum wavelength of W = 6057.8019 METHOD: Formula from Ciddor 1996, Applied Optics 62, 958 NOTES: Take care within 1 A of 2000 A. Wavelengths below 2000 A *in air* are not altered. REVISION HISTORY Written W. Landsman November 1991 Use Ciddor (1996) formula for better accuracy in the infrared Added optional output vector, W Landsman Mar 2011 Iterate for better precision W.L./D. Schlegel Mar 2011
(See $IDLUTILS_DIR/goddard/pro/astro/airtovac.pro)
AITOFF
NAME: AITOFF PURPOSE: Convert longitude, latitude to X,Y using an AITOFF projection. EXPLANATION: This procedure can be used to create an all-sky map in Galactic coordinates with an equal-area Aitoff projection. Output map coordinates are zero longitude centered. CALLING SEQUENCE: AITOFF, L, B, X, Y INPUTS: L - longitude - scalar or vector, in degrees B - latitude - same number of elements as L, in degrees OUTPUTS: X - X coordinate, same number of elements as L. X is normalized to be between -180 and 180 Y - Y coordinate, same number of elements as L. Y is normalized to be between -90 and 90. NOTES: See AIPS memo No. 46, page 4, for details of the algorithm. This version of AITOFF assumes the projection is centered at b=0 degrees. REVISION HISTORY: Written W.B. Landsman STX December 1989 Modified for Unix: J. Bloch LANL SST-9 5/16/91 1.1 Converted to IDL V5.0 W. Landsman September 1997
(See $IDLUTILS_DIR/goddard/pro/astro/aitoff.pro)
AITOFF_GRID
NAME: AITOFF_GRID PURPOSE: Produce an overlay of latitude and longitude lines over a plot or image EXPLANATION: The grid is plotted on the current graphics device. AITOFF_GRID assumes that the ouput plot coordinates span the x-range of -180 to 180 and the y-range goes from -90 to 90. CALLING SEQUENCE: AITOFF_GRID [,DLONG,DLAT, LABEL=, /NEW, CHARTHICK=, CHARSIZE=, FONT=, _EXTRA=] OPTIONAL INPUTS: DLONG = Optional input longitude line spacing in degrees. If left out, defaults to 30. DLAT = Optional input latitude line spacing in degrees. If left out, defaults to 30. OPTIONAL INPUT KEYWORDS: LABEL = Optional keyword specifying that the latitude and longitude lines on the prime meridian and the equator should be labeled in degrees. If LABELS is given a value of 2, i.e. LABELS=2, then the longitude labels will be in hours instead of degrees. CHARSIZE = If /LABEL is set, then CHARSIZE specifies the size of the label characters (passed to XYOUTS) CHARTHICK = If /LABEL is set, then CHARTHICK specifies the thickness of the label characters (passed to XYOUTS) FONT = scalar font graphics keyword (-1,0 or 1) for text /NEW = If this keyword is set, then AITOFF_GRID will create a new plot grid, rather than overlay an existing plot. Any valid keyword to OPLOT such as COLOR, LINESTYLE, THICK can be passed to AITOFF_GRID (though the _EXTRA facility) to to specify the color, style, or thickness of the grid lines. OUTPUTS: Draws grid lines on current graphics device. EXAMPLE: Create a labeled Aitoff grid of the Galaxy, and overlay stars at specified Galactic longitudes, glong and latitudes, glat IDL> aitoff_grid,/label,/new ;Create labeled grid IDL> aitoff, glong, glat, x,y ;Convert to X,Y coordinates IDL> plots,x,y,psym=2 ;Overlay "star" positions PROCEDURES USED: AITOFF NOTES: If labeling in hours (LABEL=2) then the longitude spacing should be a multiple of 15 degrees AUTHOR AND MODIFICATIONS: J. Bloch 1.2 6/2/91 Converted to IDL V5.0 W. Landsman September 1997 Create default plotting coords, if needed W. Landsman August 2000 Added _EXTRA, CHARTHICK, CHARSIZE keywords W. Landsman March 2001 Several tweaks, plot only hours not minutes W. Landsman January 2002 Allow FONT keyword to be passed to XYOUTS. T. Robishaw Apr. 2006
(See $IDLUTILS_DIR/goddard/pro/astro/aitoff_grid.pro)
ALTAZ2HADEC
NAME: ALTAZ2HADEC PURPOSE: Convert Horizon (Alt-Az) coordinates to Hour Angle and Declination. EXPLANATION:: Can deal with the NCP singularity. Intended mainly to be used by program hor2eq.pro CALLING SEQUENCE: ALTAZ2HADEC, alt, az, lat, ha, dec INPUTS alt - the local apparent altitude, in DEGREES, scalar or vector az - the local apparent azimuth, in DEGREES, scalar or vector, measured EAST of NORTH!!! If you have measured azimuth west-of-south (like the book MEEUS does), convert it to east of north via: az = (az + 180) mod 360 lat - the local geodetic latitude, in DEGREES, scalar or vector. OUTPUTS ha - the local apparent hour angle, in DEGREES. The hour angle is the time that right ascension of 0 hours crosses the local meridian. It is unambiguously defined. dec - the local apparent declination, in DEGREES. EXAMPLE: Arcturus is observed at an apparent altitude of 59d,05m,10s and an azimuth (measured east of north) of 133d,18m,29s while at the latitude of +43.07833 degrees. What are the local hour angle and declination of this object? IDL> altaz2hadec, ten(59,05,10), ten(133,18,29), 43.07833, ha, dec ===> Hour angle ha = 336.683 degrees Declination, dec = 19.1824 degrees The widely available XEPHEM code gets: Hour Angle = 336.683 Declination = 19.1824 REVISION HISTORY: Written Chris O'Dell Univ. of Wisconsin-Madison May 2002
(See $IDLUTILS_DIR/goddard/pro/astro/altaz2hadec.pro)
AL_LEGEND
NAME: AL_LEGEND PURPOSE: Create an annotation legend for a plot. EXPLANATION: This procedure was originally named LEGEND, but a distinct LEGEND() function was introduced into IDL V8.0. Therefore, the original LEGEND procedure in the Astronomy Library is renamed to AL_LEGEND. This procedure makes a legend for a plot. The legend can contain a mixture of symbols, linestyles, Hershey characters (vectorfont), and filled polygons (usersym). A test procedure, legendtest.pro, shows legend's capabilities. Placement of the legend is controlled with keywords like /right, /top, and /center or by using a position keyword for exact placement (position=[x,y]) or via mouse (/position). CALLING SEQUENCE: AL_LEGEND [,items][,keyword options] EXAMPLES: The call: al_legend,['Plus sign','Asterisk','Period'],psym=[1,2,3] produces: ----------------- | | | + Plus sign | | * Asterisk | | . Period | | | ----------------- Each symbol is drawn with a cgPlots command, so they look OK. Other examples are given in optional output keywords. lines = indgen(6) ; for line styles items = 'linestyle '+strtrim(lines,2) ; annotations al_legend,items,linestyle=lines ; vertical legend---upper left items = ['Plus sign','Asterisk','Period'] sym = [1,2,3] al_legend,items,psym=sym ; ditto except using symbols al_legend,items,psym=sym,/horizontal ; horizontal format al_legend,items,psym=sym,box=0 ; sans border al_legend,items,psym=sym,delimiter='=' ; embed '=' betw psym & text al_legend,items,psym=sym,margin=2 ; 2-character margin al_legend,items,psym=sym,position=[x,y] ; upper left in data coords al_legend,items,psym=sym,pos=[x,y],/norm ; upper left in normal coords al_legend,items,psym=sym,pos=[x,y],/device ; upper left in device coords al_legend,items,psym=sym,/position ; interactive position al_legend,items,psym=sym,/right ; at upper right al_legend,items,psym=sym,/bottom ; at lower left al_legenditems,psym=sym,/center ; approximately near center al_legend,items,psym=sym,number=2 ; plot two symbols, not one Plot 3 filled colored squares al_legend,items,/fill,psym=[8,8,8],colors=['red','green','blue'] Another example of the use of AL_LEGEND can be found at http://www.idlcoyote.com/cg_tips/al_legend.php INPUTS: items = text for the items in the legend, a string array. For example, items = ['diamond','asterisk','square']. You can omit items if you don't want any text labels. OPTIONAL INPUT KEYWORDS: linestyle = array of linestyle numbers If linestyle[i] < 0, then omit ith symbol or line to allow a multi-line entry. If linestyle = -99 then text will be left-justified. psym = array of plot symbol numbers. If psym[i] is negative, then a line connects pts for ith item. If psym[i] = 8, then the procedure usersym is called with vertices define in the keyword usersym. If psym[i] = 88, then use the previously defined user symbol. If 11 <= psym[i] <= 46 then David Fanning's function SYMCAT() will be used for additional symbols. (http://www.idlcoyote.com/programs/symcat.pro). Note that PSYM=10 (histogram plot mode) is not allowed since it cannot be used with the cgPlots command. vectorfont = vector-drawn characters for the sym/line column, e.g., ['!9B!3','!9C!3','!9D!3'] produces an open square, a checkmark, and a partial derivative, which might have accompanying items ['BOX','CHECK','PARTIAL DERIVATIVE']. There is no check that !p.font is set properly, e.g., -1 for X and 0 for PostScript. This can produce an error, e.g., use !20 with PostScript and !p.font=0, but allows use of Hershey *AND* PostScript fonts together. N. B.: Choose any of linestyle, psym, and/or vectorfont. If none is present, only the text is output. If more than one is present, all need the same number of elements, and normal plot behaviour occurs. By default, if psym is positive, you get one point so there is no connecting line. If vectorfont[i] = '', then cgPlots is called to make a symbol or a line, but if vectorfont[i] is a non-null string, then cgText is called. /help = flag to print header /horizontal = flag to make the legend horizontal /vertical = flag to make the legend vertical (D=vertical) background_color - color name or number to fill the legend box. Automatically sets /clear. (D = -1) box = flag to include/omit box around the legend (D=include) outline_color = color of box outline (D = !P.color) bthick = thickness of the legend box (D = !P.thick) charsize = just like !p.charsize for plot labels charthick = just like !p.charthick for plot labels clear = flag to clear the box area before drawing the legend colors = array of colors names or numbers for plot symbols/lines See cgCOLOR for list of color names. Default is 'Opposite' If you are using index colors (0-255), then supply color as a byte, integer or string, but not as a long, which will be interpreted as a decomposed color. See http://www.idlcoyote.com/cg_tips/legcolor.php delimiter = embedded character(s) between symbol and text (D=none) font = scalar font graphics keyword (-1,0 or 1) for text linsize = Scale factor for line length (0-1), default = 1 Set to 0 to give a dot, 0.5 give half default line length margin = margin around text measured in characters and lines number = number of plot symbols to plot or length of line (D=1) spacing = line spacing (D=bit more than character height) position = data coordinates of the /top (D) /left (D) of the legend pspacing = psym spacing (D=3 characters) (when number of symbols is greater than 1) textcolors = array of color names or numbers for text. See cgCOLOR for a list of color names. Default is 'Opposite' of background thick = array of line thickness numbers (D = !P.thick), if used, then linestyle must also be specified normal = use normal coordinates for position, not data device = use device coordinates for position, not data /window - if set then send legend to a resizeable graphics window usersym = 2-D array of vertices, cf. usersym in IDL manual. (/USERSYM =square, default is to use existing USERSYM definition) /fill = flag to fill the usersym /left_legend = flag to place legend snug against left side of plot window (D) /right_legend = flag to place legend snug against right side of plot window. If /right,pos=[x,y], then x is position of RHS and text runs right-to-left. /top_legend = flag to place legend snug against top of plot window (D) /bottom = flag to place legend snug against bottom of plot window /top,pos=[x,y] and /bottom,pos=[x,y] produce same positions. If LINESTYLE, PSYM, VECTORFONT, SYMSIZE, THICK, COLORS, or TEXTCOLORS are supplied as scalars, then the scalar value is set for every line or symbol in the legend. Outputs: legend to current plot device OPTIONAL OUTPUT KEYWORDS: corners = 4-element array, like !p.position, of the normalized coords for the box (even if box=0): [llx,lly,urx,ury]. Useful for multi-column or multi-line legends, for example, to make a 2-column legend, you might do the following: c1_items = ['diamond','asterisk','square'] c1_psym = [4,2,6] c2_items = ['solid','dashed','dotted'] c2_line = [0,2,1] al_legend,c1_items,psym=c1_psym,corners=c1,box=0 al_legend,c2_items,line=c2_line,corners=c2,box=0,pos=[c1[2],c1[3]] c = [c1[0]<c2[0],c1[1]<c2[1],c1[2]>c2[2],c1[3]>c2[3]] cgplots,[c[0],c[0],c[2],c[2],c[0]],[c[1],c[3],c[3],c[1],c[1]],/norm Useful also to place the legend. Here's an automatic way to place the legend in the lower right corner. The difficulty is that the legend's width is unknown until it is plotted. In this example, the legend is plotted twice: the first time in the upper left, the second time in the lower right. al_legend,['1','22','333','4444'],linestyle=indgen(4),corners=corners ; BOGUS LEGEND---FIRST TIME TO REPORT CORNERS xydims = [corners[2]-corners[0],corners[3]-corners[1]] ; SAVE WIDTH AND HEIGHT chdim=[!d.x_ch_size/float(!d.x_size),!d.y_ch_size/float(!d.y_size)] ; DIMENSIONS OF ONE CHARACTER IN NORMALIZED COORDS pos = [!x.window[1]-chdim[0]-xydims[0] $ ,!y.window[0]+chdim[1]+xydims[1]] ; CALCULATE POSITION FOR LOWER RIGHT cgplot,findgen(10) ; SIMPLE PLOT; YOU DO WHATEVER YOU WANT HERE. al_legend,['1','22','333','4444'],linestyle=indgen(4),pos=pos ; REDO THE LEGEND IN LOWER RIGHT CORNER You can modify the pos calculation to place the legend where you want. For example to place it in the upper right: pos = [!x.window[1]-chdim[0]-xydims[0],!y.window[1]-xydims[1]] Common blocks: none Procedure: If keyword help is set, call doc_library to print header. See notes in the code. Much of the code deals with placement of the legend. The main problem with placement is not being able to sense the length of a string before it is output. Some crude approximations are used for centering. Restrictions: Here are some things that aren't implemented. - An orientation keyword would allow lines at angles in the legend. - An array of usersyms would be nice---simple change. - An order option to interchange symbols and text might be nice. - Somebody might like double boxes, e.g., with box = 2. - Another feature might be a continuous bar with ticks and text. - There are no guards to avoid writing outside the plot area. - There is no provision for multi-line text, e.g., '1st line!c2nd line' Sensing !c would be easy, but !c isn't implemented for PostScript. A better way might be to simply output the 2nd line as another item but without any accompanying symbol or linestyle. A flag to omit the symbol and linestyle is linestyle[i] = -1. - There is no ability to make a title line containing any of titles for the legend, for the symbols, or for the text. Side Effects: Modification history: write, 24-25 Aug 92, F K Knight (knight@ll.mit.edu) allow omission of items or omission of both psym and linestyle, add corners keyword to facilitate multi-column legends, improve place- ment of symbols and text, add guards for unequal size, 26 Aug 92, FKK add linestyle(i)=-1 to suppress a single symbol/line, 27 Aug 92, FKK add keyword vectorfont to allow characters in the sym/line column, 28 Aug 92, FKK add /top, /bottom, /left, /right keywords for automatic placement at the four corners of the plot window. The /right keyword forces right-to-left printing of menu. 18 Jun 93, FKK change default position to data coords and add normal, data, and device keywords, 17 Jan 94, FKK add /center keyword for positioning, but it is not precise because text string lengths cannot be known in advance, 17 Jan 94, FKK add interactive positioning with /position keyword, 17 Jan 94, FKK allow a legend with just text, no plotting symbols. This helps in simply describing a plot or writing assumptions done, 4 Feb 94, FKK added thick, symsize, and clear keyword Feb 96, W. Landsman HSTX David Seed, HR Wallingford, d.seed@hrwallingford.co.uk allow scalar specification of keywords, Mar 96, W. Landsman HSTX added charthick keyword, June 96, W. Landsman HSTX Made keyword names left,right,top,bottom,center longer, Aug 16, 2000, Kim Tolbert Added ability to have regular text lines in addition to plot legend lines in legend. If linestyle is -99 that item is left-justified. Previously, only option for no sym/line was linestyle=-1, but then text was lined up after sym/line column. 10 Oct 2000, Kim Tolbert Make default value of thick = !P.thick W. Landsman Jan. 2001 Don't overwrite existing USERSYM definition W. Landsman Mar. 2002 Added outline_color BT 24 MAY 2004 Pass font keyword to cgText commands. M. Fitzgerald, Sep. 2005 Default spacing, pspacing should be relative to charsize. M. Perrin, July 2007 Don't modify position keyword A. Kimball/ W. Landsman Jul 2007 Small update to Jul 2007 for /NORMAL coords. W. Landsman Aug 2007 Use SYMCAT() plotting symbols for 11<=PSYM<=46 W. Landsman Nov 2009 Make a sharper box edge T. Robishaw/W.Landsman July 2010 Added BTHICK keyword W. Landsman October 2010 Added BACKGROUND_COLOR keyword W. Landsman February 2011 Incorporate Coyote graphics W. Landsman February 2011 Added LINSIZE keyword W.L./V.Gonzalez May 2011 Fixed a small problem with Convert_Coord when the Window keyword is set. David Fanning, May 2011. Fixed problem when /clear and /Window are set J. Bailin/WL May 2011 CGQUERY was called instead of CGCONTROL W.L. June 2011 Fixed typo preventing BTHICK keyword from working W.L. Dec 2011 Remove call to SYMCAT() W.L. Dec 2011 Changed the way the WINDOW keyword adds commands to cgWindow, and now default to BACKGROUND for background color. 1 Feb 2012 David Fanning Allow 1 element SYMSIZE for vector input, WL Apr 2012.
(See $IDLUTILS_DIR/goddard/pro/plot/al_legend.pro)
APER
NAME: APER PURPOSE: Compute concentric aperture photometry (adapted from DAOPHOT) EXPLANATION: APER can compute photometry in several user-specified aperture radii. A separate sky value is computed for each source using specified inner and outer sky radii. CALLING SEQUENCE: APER, image, xc, yc, [ mags, errap, sky, skyerr, phpadu, apr, skyrad, badpix, /NAN, /EXACT, /FLUX, PRINT = , /SILENT, /MEANBACK, MINSKY=, SETSKYVAL = ] INPUTS: IMAGE - input image array XC - vector of x coordinates. YC - vector of y coordinates OPTIONAL INPUTS: PHPADU - Photons per Analog Digital Units, numeric scalar. Converts the data numbers in IMAGE to photon units. (APER assumes Poisson statistics.) APR - Vector of up to 12 REAL photometry aperture radii. SKYRAD - Two element vector giving the inner and outer radii to be used for the sky annulus. Ignored if the SETSKYVAL keyword is set. BADPIX - Two element vector giving the minimum and maximum value of a good pixel. If badpix is not supplied or if BADPIX[0] is equal to BADPIX[1] then it is assumed that there are no bad pixels. Note that fluxes will not be computed for any star with a bad pixel within the aperture area, but that bad pixels will be simply ignored for the sky computation. The BADPIX parameter is ignored if the /NAN keyword is set. OPTIONAL KEYWORD INPUTS: CLIPSIG - if /MEANBACK is set, then this is the number of sigma at which to clip the background. Default=3 CONVERGE_NUM: if /MEANBACK is set then if the proportion of rejected pixels is less than this fraction, the iterations stop. Default=0.02, i.e., iteration stops if fewer than 2% of pixels excluded. /EXACT - By default, APER counts subpixels, but uses a polygon approximation for the intersection of a circular aperture with a square pixel (and normalizes the total area of the sum of the pixels to exactly match the circular area). If the /EXACT keyword, then the intersection of the circular aperture with a square pixel is computed exactly. The /EXACT keyword is much slower and is only needed when small (~2 pixels) apertures are used with very undersampled data. /FLUX - By default, APER uses a magnitude system where a magnitude of 25 corresponds to 1 flux unit. If set, then APER will keep results in flux units instead of magnitudes. MAXITER if /MEANBACK is set then this is the ceiling on number of clipping iterations of the background. Default=5 /MEANBACK - if set, then the background is computed using the 3 sigma clipped mean (using meanclip.pro) rather than using the mode computed with mmm.pro. This keyword is useful for the Poisson count regime or where contamination is known to be minimal. MINSKY - Integer giving mininum number of sky values to be used with MMM APER will not compute a flux if fewer valid sky elements are within the sky annulus. Default = 20. /NAN - If set then APER will check for NAN values in the image. /NAN takes precedence over the BADPIX parameter. Note that fluxes will not be computed for any star with a NAN pixel within the aperture area, but that NAN pixels will be simply ignored for the sky computation. PRINT - if set and non-zero then APER will also write its results to a file aper.prt. One can specify the output file name by setting PRINT = 'filename'. READNOISE - Scalar giving the read noise (or minimum noise for any pixel. This value is passed to the procedure mmm.pro when computing the sky, and is only need for images where the noise is low, and pixel values are quantized. /SILENT - If supplied and non-zero then no output is displayed to the terminal. SETSKYVAL - Use this keyword to force the sky to a specified value rather than have APER compute a sky value. SETSKYVAL can either be a scalar specifying the sky value to use for all sources, or a 3 element vector specifying the sky value, the sigma of the sky value, and the number of elements used to compute a sky value. The 3 element form of SETSKYVAL is needed for accurate error budgeting. OUTPUTS: MAGS - NAPER by NSTAR array giving the magnitude for each star in each aperture. (NAPER is the number of apertures, and NSTAR is the number of stars). If the /FLUX keyword is not set, then a flux of 1 digital unit is assigned a zero point magnitude of 25. ERRAP - NAPER by NSTAR array giving error for each star. If a magnitude could not be determined then ERRAP = 9.99 (if in magnitudes) or ERRAP = !VALUES.F_NAN (if /FLUX is set). SKY - NSTAR element vector giving sky value for each star in flux units SKYERR - NSTAR element vector giving error in sky values EXAMPLE: Determine the flux and error for photometry radii of 3 and 5 pixels surrounding the position 234.2,344.3 on an image array, im. Compute the partial pixel area exactly. Assume that the flux units are in Poisson counts, so that PHPADU = 1, and the sky value is already known to be 1.3, and that the range [-32767,80000] for bad low and bad high pixels IDL> aper, im, 234.2, 344.3, flux, eflux, sky,skyerr, 1, [3,5], -1, $ [-32767,80000],/exact, /flux, setsky = 1.3 PROCEDURES USED: GETOPT, MMM, PIXWT(), STRN(), STRNUMBER() NOTES: Reasons that a valid magnitude cannot be computed include the following: (1) Star position is too close (within 0.5 pixels) to edge of the frame (2) Less than 20 valid pixels available for computing sky (3) Modal value of sky could not be computed by the procedure MMM (4) *Any* pixel within the aperture radius is a "bad" pixel (5) The total computed flux is negative. In this case the negative flux and error are returned. For the case where the source is fainter than the background, APER will return negative fluxes if /FLUX is set, but will otherwise give invalid data (since negative fluxes can't be converted to magnitudes) APER was modified in June 2000 in two ways: (1) the /EXACT keyword was added (2) the approximation of the intersection of a circular aperture with square pixels was improved (i.e. when /EXACT is not used) REVISON HISTORY: Adapted to IDL from DAOPHOT June, 1989 B. Pfarr, STX FLUX keyword added J. E. Hollis, February, 1996 SETSKYVAL keyword, increase maxsky W. Landsman, May 1997 Work for more than 32767 stars W. Landsman, August 1997 Don't abort for insufficient sky pixels W. Landsman May 2000 Added /EXACT keyword W. Landsman June 2000 Allow SETSKYVAL = 0 W. Landsman December 2000 Set BADPIX[0] = BADPIX[1] to ignore bad pixels W. L. January 2001 Fix chk_badpixel problem introduced Jan 01 C. Ishida/W.L. February 2001 Set bad fluxes and error to NAN if /FLUX is set W. Landsman Oct. 2001 Remove restrictions on maximum sky radius W. Landsman July 2003 Added /NAN keyword W. Landsman November 2004 Set badflux=0 if neither /NAN nor badpix is set M. Perrin December 2004 Added READNOISE keyword W. Landsman January 2005 Added MEANBACK keyword W. Landsman October 2005 Correct typo when /EXACT and multiple apertures used. W.L. Dec 2005 Remove VMS-specific code W.L. Sep 2006 Add additional keywords if /MEANBACK is set W.L Nov 2006 Allow negative fluxes if /FLUX is set W.L. Mar 2008 Previous update would crash if first star was out of range W.L. Mar 2008 Fix floating equality test for bad magnitudes W.L./J.van Eyken Jul 2009 Added MINSKY keyword W.L. Dec 2011
(See $IDLUTILS_DIR/goddard/pro/idlphot/aper.pro)
ARCBAR
NAME: ARCBAR PURPOSE: Draw an arc bar on an image showing the astronomical plate scale CALLING SEQUENCE: ARCBAR, hdr, arclen,[ COLOR= , /DATA, LABEL= , /NORMAL, POSITION =, /SECONDS, SIZE=, THICK=, FONT= ] INPUTS: hdr - image FITS header with astrometry, string array arclen - numeric scalar giving length of bar in arcminutes (default) or arcseconds (if /SECONDS is set) OPTIONAL KEYWORD INPUTS: COLOR - name or integer scalar specifying the color to draw the arcbar See cgColor for a list of available color names /DATA - if set and non-zero, then the POSITION keyword is given in data units LABEL - string giving user defined label for bar. Default label is size of bar in arcminutes /NORMAL - if this keyword is set and non-zero, then POSITION is given in normalized units POSITION - 2 element vector giving the (X,Y) position in device units (or normalized units if /NORMAL is set, or data units if /DATA is set) at which to place the scale bar. If not supplied, then the user will be prompted to place the cursor at the desired position /SECONDS - if set, then arlen is specified in arcseconds rather than arcminutes SIZE - scalar specifying character size of label, default = 1.0 THICK - Character thickness of the label, default = !P.THICK FONT - scalar font graphics keyword (-1,0 or 1) for text EXAMPLE: Place a 3' arc minute scale bar, at position 300,200 of the current image window, (which is associated with a FITS header, HDR) IDL> arcbar, HDR, 3, pos = [300,200] RESTRICTIONS: When using using a device with scalable pixels (e.g. postscript) the data coordinate system must be established before calling ARCBAR. If data coordinates are not set, then ARCBAR assumes that the displayed image size is given by the NAXIS1 keyword in the FITS header. PROCEDURE CALLS: AD2XY, EXTAST, GSSSADXY, SXPAR(), cgPlot, cgText REVISON HISTORY: written by L. Taylor (STX) from ARCBOX (Boothman) modified for Version 2 IDL, B. Pfarr, STX, 4/91 New ASTROMETRY structures W.Landsman, HSTX, Jan 94 Recognize a GSSS header W. Landsman June 94 Added /NORMAL keyword W. Landsman Feb. 96 Use NAXIS1 for postscript if data coords not set, W. Landsman Aug 96 Fixed typo for postscript W. Landsman Oct. 96 Account for zeropoint offset in postscript W. Landsman Apr 97 Added /DATA, /SECONDS keywords W. Landsman July 1998 Use device-independent label offset W. Landsman August 2001 Allow font keyword to be passed. T. Robishaw Apr. 2006 Remove obsolete TVCURSOR command W. Landsman Jul 2007 Use Coyote Graphics W. Landsman February 2011
(See $IDLUTILS_DIR/goddard/pro/astro/arcbar.pro)
ARROWS
NAME: ARROWS PURPOSE: To display "weathervane" directional arrows on an astronomical image EXPLANATION: Overlays a graphic showing orientation of North and East. CALLING SEQUENCE: ARROWS,h, [ xcen, ycen, ARROWLEN= , CHARSIZE= COLOR= , /DATA FONT=, /NORMAL, /NOTVERTEX, THICK= ] INPUTS: h - FITS header array, must include astrometry OPTIONAL INPUTS: xcen,ycen - numeric scalars, specifying the center position of arrows. Position in device units unless the /NORMALIZED keyword is specified. If not supplied, then ARROWS will prompt for xcen and ycen OPTIONAL KEYWORD INPUTS: arrowlen - length of arrows in terms of normal Y size of vector-drawn character, default = 3.5, floating point scalar charsize - character size, default = 2.0, floating point scalar color - color name or number for the arrows and NE letters. See cgCOLOR() for a list of color names. Data - if this keyword is set and nonzero, the input center (xcen, ycen) is understood to be in data coordinates font - IDL vector font number (1-20) to use to display NE letters. For example, set font=13 to use complex italic font. NotVertex - Normally (historically) the specified xcen,ycen indicated the position of the vertex of the figure. If this keyword is set, the xcen,ycen coordinates refer to a sort of 'center of mass' of the figure. This allows the figure to always appear with the area irregardless of the rotation angle. Normal - if this keyword is set and nonzero, the input center (xcen,ycen) is taken to be in normalized coordinates. The default is device coordinates. thick - line thickness, default = 2.0, floating point scalar OUTPUTS: none EXAMPLE: Draw a weathervane at (400,100) on the currently active window, showing the orientation of the image associated with a FITS header, hdr IDL> arrows, hdr, 400, 100 METHOD: Uses EXTAST to EXTract ASTrometry from the FITS header. The directions of North and East are computed and the procedure ONE_ARROW called to create the "weathervane". PROCEDURES USED: GETROT - Computes rotation from the FITS header ONE_ARROW - Draw a labeled arrow ZPARCHECK REVISON HISTORY: written by B. Boothman 2/5/86 Recoded with new procedures ONE_ARROW, ONE_RAY. R.S.Hill,HSTX,5/20/92 Added separate determination for N and E arrow to properly display arrows irregardless of handedness or other peculiarities and added /NotVertex keyword to improve positioning of figure. E.Deutsch 1/10/93 Added /DATA and /NORMAL keywords W. Landsman July 1993 Recognize GSSS header W. Landsman June 1993 Added /FONT keyword W. Landsman April 1995 Modified to work correctly for COLOR=0 J.Wm.Parker, HITC 1995 May 25 Work correctly for negative CDELT values W. Landsman Feb. 1996 Use GETROT to compute rotation W. Landsman June 2003 Restored /NotVertex keyword which was not working after June 2003 change W. Landsman January 2004
(See $IDLUTILS_DIR/goddard/pro/astro/arrows.pro)
ASINH
NAME: ASINH PURPOSE: Return the inverse hyperbolic sine of the argument EXPLANATION: The inverse hyperbolic sine is used for the calculation of asinh magnitudes, see Lupton et al. (1999, AJ, 118, 1406) CALLING SEQUENCE result = asinh( x) INPUTS: X - hyperbolic sine, numeric scalar or vector or multidimensional array (not complex) OUTPUT: result - inverse hyperbolic sine, same number of elements as X double precision if X is double, otherwise floating pt. METHOD: Expression given in Numerical Recipes, Press et al. (1992), eq. 5.6.7 Note that asinh(-x) = -asinh(x) and that asinh(0) = 0. and that if y = asinh(x) then x = sinh(y). REVISION HISTORY: Written W. Landsman February, 2001 Work for multi-dimensional arrays W. Landsman August 2002 Simplify coding, and work for scalars again W. Landsman October 2003
(See $IDLUTILS_DIR/goddard/pro/math/asinh.pro)
ASPECT
NAME: ASPECT PURPOSE: This function calculates and returns the normalized position coordinates necessary to put a plot with a specified aspect ratio into the currently active graphics window. It works on the display output window as well as in a PostScript output window. AUTHOR: FANNING SOFTWARE CONSULTING David Fanning, Ph.D. 1645 Sheely Drive Fort Collins, CO 80526 USA Phone: 970-221-0438 E-mail: david@idlcoyote.com Coyote's Guide to IDL Programming: http://www.idlcoyote.com/ CATEGORY: Graphics CALLING SEQUENCE: position = ASPECT(aspectRatio) INPUTS: aspectRatio: A floating point value that is the desired aspect ratio (ratio of heigth to width) of the plot in the current graphics output window. If this parameter is missing, an aspect ratio of 1.0 (a square plot) is assumed. KEYWORD PARAMETERS: MARGIN: The margin around the edges of the plot. The value must be a floating point value between 0.0 and 0.5. It is expressed in normalized coordinate units. The default margin is 0.15. WINDOWASPECT: The aspect ratio of the target window. If not provided, the value is obtained from the current graphics window. OUTPUTS: position: A four-element floating array of normalized coordinates. The order of the elements is [x0, y0, x1, y1], similar to the !P.POSITION system variable or the POSITION keyword on any IDL graphic command. EXAMPLE: To create a plot with an aspect ratio of 1:2 and a margin of 0.10 around the edge of the output window, do this: plotPosition = ASPECT(0.5, Margin=0.10) PLOT, Findgen(11), POSITION=plotPosition Notice this can be done in a single IDL command, like this: PLOT, Findgen(11), POSITION=ASPECT(0.5, Margin=0.10) MODIFICATION HISTORY: Written by: David Fanning, November 1996. Added better error checking, 18 Feb 1997, DWF. Added WindowAspect keyword. 10 Feb 2000. DWF Added double precision tolerance for aspectRatio. 9 NOV 2001 BT
(See $IDLUTILS_DIR/goddard/pro/coyote/aspect.pro)
ASTDISP
NAME: ASTDISP PURPOSE: Print astronomical and pixel coordinates in a standard format EXPLANATION: This procedure (ASTrometry DISPlay) prints the astronomical and pixel coordinates in a standard format. X,Y must be supplied. RA,DEC may also be supplied, and a data number (DN) may also be supplied. With use of the Coords= keyword, a string containing the formatted data can be returned in addition or instead (with /silent) of printing. CALLING SEQUENCE: ASTDISP, x, y, [Ra, Dec, DN, COORD = , /SILENT ] INPUT: X - The X pixel coordinate(s), scalar or vector Y - The Y pixel coordinate(s), scalar or vector OPTIONAL INPUTS: RA - Right Ascension in *degrees*, scalar or vector DEC - DEClination in *degrees*, scalar or vector (if RA is supplied, DEC must also be supplied) DN - Data Number or Flux values Each of the inputs X,Y, RA, DEC, DN should have the same number of elements OPTIONAL INPUT KEYWORDS: SILENT Prevents printing. Only useful when used with Coords= OUTPUT: Printed positions in both degrees and sexigesimal format All passed variables remain unchanged OPTIONAL KEYWORD OUTPUT: COORDS Returns the formatted coordinates in a string PROCEDURES CALLED: ADSTRING - used to format the RA and Dec HISTORY: 10-AUG-90 Version 1 written by Eric W. Deutsch 20-AUG-91 Converted to standard header. Vectorized Code. E. Deutsch 20-NOV-92 Added Coords= and /silent. E.Deutsch Converted to IDL V5.0 W. Landsman September 1997
(See $IDLUTILS_DIR/goddard/pro/astro/astdisp.pro)
ASTRO
NAME: ASTRO PURPOSE: Interactive utility for precession and coordinate conversion. CALLING SEQUENCE: ASTRO, [ selection, EQUINOX =, /FK4] OPTIONAL INPUT: SELECTION - Scalar Integer (0-6) giving the the particular astronomical utility to be used. (0) Precession, (1) RA, Dec (2000) to Galactic coordinates, (2) Galactic to RA,Dec (2000) (3) RA,Dec (2000) to Ecliptic, (4) Ecliptic to RA, Dec, (5) Ecliptic to Galactic, (6) Galactic to Ecliptic. Program will prompt for SELECTION if this parameter is omitted. OPTIONAL KEYWORD INPUT: EQUINOX - numeric scalar specifying the equinox to use when converting between celestial and other coordinates. If not supplied, then the RA and Dec will be assumed to be in EQUINOX J2000. This keyword is ignored by the precession utility. For example, to convert from RA and DEC (J1975) to Galactic coordinates: IDL> astro, 1, E=1975 /FK4 - If this keyword is set and nonzero, then calculations are done in the FK4 system. For example, to convert from RA and Dec (B1975) to Galactic coordinates IDL> astro,1, E=1975,/FK4 METHOD: ASTRO uses PRECESS to compute precession, and EULER to compute coordinate conversions. The procedure GET_COORDS is used to read the coordinates, and ADSTRING to format the RA,Dec output. NOTES: (1) ASTRO temporarily sets !QUIET to suppress compilation messages and keep a pretty screen display. (2) ASTRO was changed in December 1998 to use J2000 as the default equinox, **and may be incompatible with earlier calls.*** (3) A nice online page for coordinate conversions is available at http://heasarc.gsfc.nasa.gov/cgi-bin/Tools/convcoord/convcoord.pl PROCEDURES USED: Procedures: GET_COORDS, EULER Function: ADSTRING REVISION HISTORY Written, W. Landsman November 1987 Code cleaned up W. Landsman October 1991 Added Equinox keyword, call to GET_COORDS, W. Landsman April, 1992 Allow floating point equinox input J. Parker/W. Landsman July 1996 Make FK5 the default, add FK4 keyword
(See $IDLUTILS_DIR/goddard/pro/astro/astro.pro)
ASTROLIB
NAME: ASTROLIB PURPOSE: Add the non-standard system variables used by the IDL Astronomy Library EXPLANATION: Also defines the environment variable ASTRO_DATA pointing to the directory containing data files associated with the IDL Astronomy library (system dependent -- user must edit the third line in the program below). CALLING SEQUENCE: ASTROLIB INPUTS: None. OUTPUTS: None. METHOD: The non-standard system variables !PRIV, !TEXTUNIT, and !TEXTOUT are added using DEFSYSV. REVISION HISTORY: Written, Wayne Landsman, July 1986. Use DEFSYSV instead of ADDSYSVAR December 1990 Test for system variable existence before definition July 2001 Assume since V55, remove VMS support W. Landsman Sep 2006 Remove !Debug, comment out ASTRO_DATA definition WL Jan 2009
(See $IDLUTILS_DIR/goddard/pro/misc/astrolib.pro)
AUTOHIST
NAME: AUTOHIST PURPOSE: Draw a histogram using automatic bin-sizing. EXPLANATION AUTOHIST chooses a number of bins (initially, SQRT(2*N). If this leads to a histogram in which > 1/5 of the central 50% of the bins are empty, it decreases the number of bins and tries again. The minimum # bins is 5. The max=199. Called by HISTOGAUSS and HALFAGAUSS. CALLING SEQUENCE: AUTOHIST, Sample, XLines, Ylines, XCenters, YCenters, [/NOPLOT, ] ...Plotting Keywords INPUT: Sample = the vector to be histogrammed OUTPUT: XLINES = vector of x coordinates of the points that trace the rectangular histogram bins YLINES = vector of y coordinates. To draw the histogram plot YLINES vs XLINES XCENTERS = the x values of the bin centers YCENTERS = the corresponding y values OPTIONAL INPUT KEYWORDS: /NOPLOT If set, nothing is drawn Any plotting keywords (e.g. XTITLE) may be supplied to AUTOHIST through the _EXTRA facility. REVISION HISTORY: Written, H. Freudenreich, STX, 1/91 1998 March 17 - Changed shading of histogram. RSH, RSTX V5.0 update, _EXTRA keywords W. Landsman April 2002 Added NOCLIP keyword for POLYFILL call C. Paxson/W. Landsman July 2003 Use Coyote graphics W. Landsman Feb 2011
(See $IDLUTILS_DIR/goddard/pro/robust/autohist.pro)
AVG
NAME: AVG PURPOSE: Return the average value of an array, or 1 dimension of an array EXPLANATION: Calculate the average value of an array, or calculate the average value over one dimension of an array as a function of all the other dimensions. In 2009, a DIMENSION keyword was added to the IDL MEAN() function, giving it the same capability as AVG(). Thus, the use of AVG() is now **deprecated** in favor of the MEAN() function. CALLING SEQUENCE: RESULT = AVG( ARRAY, [ DIMENSION, /NAN, /DOUBLE ] ) INPUTS: ARRAY = Input array. May be any type except string. OPTIONAL INPUT PARAMETERS: DIMENSION = Optional dimension to do average over, integer scalar OPTIONAL KEYWORD INPUT: /NAN - Set this keyword to cause the routine to check for occurrences of the IEEE floating-point value NaN in the input data. Elements with the value NaN are treated as missing data. /DOUBLE - By default, if the input Array is double-precision, complex, or double complex, the result is of the same type; 64 bit integers are also returned as double. Otherwise the result the result is floating-point. Use of the /DOUBLE keyword forces a double precision output. Note that internal computations are always done in double precision. OUTPUTS: The average value of the array when called with one parameter. If DIMENSION is passed, then the result is an array with all the dimensions of the input array except for the dimension specified, each element of which is the average of the corresponding vector in the input array. For example, if A is an array with dimensions of (3,4,5), then the command B = AVG(A,1) is equivalent to B = FLTARR(3,5) FOR J = 0,4 DO BEGIN FOR I = 0,2 DO BEGIN B[I,J] = TOTAL( A[I,*,J] ) / 4. ENDFOR ENDFOR RESTRICTIONS: Dimension specified must be valid for the array passed; otherwise the input array is returned as the output array. PROCEDURE: AVG(ARRAY) = TOTAL(ARRAY, /DOUBLE)/N_ELEMENTS(ARRAY) when called with one parameter. MODIFICATION HISTORY: William Thompson Applied Research Corporation July, 1986 8201 Corporate Drive Landover, MD 20785 Converted to Version 2 July, 1990 Replace SUM call with TOTAL W. Landsman May, 1992 Converted to IDL V5.0 W. Landsman September 1997 Added /NAN keyword W. Landsman July 2000 Accept a scalar input value W. Landsman/jimm@berkeley November 2000 Internal calculations always in double precision W. Landsman March 2002 Return NAN if all values in array are NAN W. Landsman April 2002 Fixed coding bug if all values in array are NAN W. Landsman Jan 2004
(See $IDLUTILS_DIR/goddard/pro/math/avg.pro)
BARYVEL
NAME: BARYVEL PURPOSE: Calculates heliocentric and barycentric velocity components of Earth. EXPLANATION: BARYVEL takes into account the Earth-Moon motion, and is useful for radial velocity work to an accuracy of ~1 m/s. CALLING SEQUENCE: BARYVEL, dje, deq, dvelh, dvelb, [ JPL = ] INPUTS: DJE - (scalar) Julian ephemeris date. DEQ - (scalar) epoch of mean equinox of dvelh and dvelb. If deq=0 then deq is assumed to be equal to dje. OUTPUTS: DVELH: (vector(3)) heliocentric velocity component. in km/s DVELB: (vector(3)) barycentric velocity component. in km/s The 3-vectors DVELH and DVELB are given in a right-handed coordinate system with the +X axis toward the Vernal Equinox, and +Z axis toward the celestial pole. OPTIONAL KEYWORD SET: JPL - if /JPL set, then BARYVEL will call the procedure JPLEPHINTERP to compute the Earth velocity using the full JPL ephemeris. The JPL ephemeris FITS file JPLEPH.405 must exist in either the current directory, or in the directory specified by the environment variable ASTRO_DATA. Alternatively, the JPL keyword can be set to the full path and name of the ephemeris file. A copy of the JPL ephemeris FITS file is available in http://idlastro.gsfc.nasa.gov/ftp/data/ PROCEDURES CALLED: Function PREMAT() -- computes precession matrix JPLEPHREAD, JPLEPHINTERP, TDB2TDT - if /JPL keyword is set NOTES: Algorithm taken from FORTRAN program of Stumpff (1980, A&A Suppl, 41,1) Stumpf claimed an accuracy of 42 cm/s for the velocity. A comparison with the JPL FORTRAN planetary ephemeris program PLEPH found agreement to within about 65 cm/s between 1986 and 1994 If /JPL is set (using JPLEPH.405 ephemeris file) then velocities are given in the ICRS system; otherwise in the FK4 system. EXAMPLE: Compute the radial velocity of the Earth toward Altair on 15-Feb-1994 using both the original Stumpf algorithm and the JPL ephemeris IDL> jdcnv, 1994, 2, 15, 0, jd ;==> JD = 2449398.5 IDL> baryvel, jd, 2000, vh, vb ;Original algorithm ==> vh = [-17.07243, -22.81121, -9.889315] ;Heliocentric km/s ==> vb = [-17.08083, -22.80471, -9.886582] ;Barycentric km/s IDL> baryvel, jd, 2000, vh, vb, /jpl ;JPL ephemeris ==> vh = [-17.07236, -22.81126, -9.889419] ;Heliocentric km/s ==> vb = [-17.08083, -22.80484, -9.886409] ;Barycentric km/s IDL> ra = ten(19,50,46.77)*15/!RADEG ;RA in radians IDL> dec = ten(08,52,3.5)/!RADEG ;Dec in radians IDL> v = vb[0]*cos(dec)*cos(ra) + $ ;Project velocity toward star vb[1]*cos(dec)*sin(ra) + vb[2]*sin(dec) REVISION HISTORY: Jeff Valenti, U.C. Berkeley Translated BARVEL.FOR to IDL. W. Landsman, Cleaned up program sent by Chris McCarthy (SfSU) June 1994 Converted to IDL V5.0 W. Landsman September 1997 Added /JPL keyword W. Landsman July 2001 Documentation update W. Landsman Dec 2005
(See $IDLUTILS_DIR/goddard/pro/astro/baryvel.pro)
BITGET
NAME: BITGET PURPOSE: Returns the bit value (0 or 1) of a specified bit in a supplied number. AUTHOR: FANNING SOFTWARE CONSULTING David Fanning, Ph.D. 1645 Sheely Drive Fort Collins, CO 80526 USA Phone: 970-221-0438 E-mail: david@idlcoyote.com Coyote's Guide to IDL Programming: http://www.idlcoyote.com CATEGORY: Utilities CALLING SEQUENCE: bitValue = BitGet(number, bit) INPUT_PARAMETERS: number: The input number. Should be a scalar integer. If not, it is converted to one by rounding. bit: The number of the bit you are interested in. A value between 0 and 63. If not supplied, all 64 bit values of the number are returned. May be an array of bit numbers. OUTPUT_PARAMETERS: bitValue: The value, 0 or 1, of the specified bit in the number. KEYWORDS: SILENT: If set, suppresses informational messages regarding rounding operations. MODIFICATION HISTORY: Written by David W. Fanning, 14 June 2006.
(See $IDLUTILS_DIR/goddard/pro/coyote/bitget.pro)
BIWEIGHT_MEAN
NAME: BIWEIGHT_MEAN PURPOSE: Calculate the center and dispersion (like mean and sigma) of a distribution using bisquare weighting. CALLING SEQUENCE: Mean = BIWEIGHT_MEAN( Vector, [ Sigma, Weights ] ) INPUTS: Vector = Distribution in vector form OUTPUT: Mean - The location of the center. OPTIONAL OUTPUT ARGUMENTS: Sigma = An outlier-resistant measure of the dispersion about the center, analogous to the standard deviation. Weights = The weights applied to the data in the last iteration, floating point vector NOTES: Since a sample mean scaled by sigma/sqrt(N), has a Student's T distribution, the half-width of the 95% confidence interval for the sample mean can be determined as follows: ABS( T_CVF( .975, .7*(N-1) )*SIGMA/SQRT(N) ) where N = number of points, and 0.975 = 1 - (1 - 0.95)/2. PROCEDURES USED: ROBUST_SIGMA() REVISION HISTORY Written, H. Freudenreich, STX, 12/89 Modified 2/94, H.T.F.: use a biweighted standard deviation rather than median absolute deviation. Modified 2/94, H.T.F.: use the fractional change in SIGMA as the convergence criterion rather than the change in center/SIGMA. Modified May 2002 Use MEDIAN(/EVEN) Modified October 2002, Faster computation of weights Corrected documentation on 95% confidence interval of mean P.Broos/W. Landsman July 2003
(See $IDLUTILS_DIR/goddard/pro/robust/biweight_mean.pro)
BLINK
NAME: BLINK PURPOSE: To allow the user to alternatively examine two or more windows within a single window. CALLING SEQUENCE: BLINK, Wndw [, T] INPUTS: Wndw A vector containing the indices of the windows to blink. T The time to wait, in seconds, between blinks. This is optional and set to 1 if not present. OUTPUTS: None. PROCEDURE: The images contained in the windows given are written to a pixmap. The contents of the the windows are copied to a display window, in order, until a key is struck. EXAMPLE: Blink windows 0 and 2 with a wait time of 3 seconds IDL> blink, [0,2], 3 MODIFICATION HISTORY: Written by Michael R. Greason, STX, 2 May 1990. Allow different size windows Wayne Landsman August, 1991 Converted to IDL V5.0 W. Landsman September 1997
(See $IDLUTILS_DIR/goddard/pro/tv/blink.pro)
BLKSHIFT
NAME: BLKSHIFT AUTHOR: Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770 craigm@lheamail.gsfc.nasa.gov PURPOSE: Shift a block of data to a new position in a file (possibly overlapping) CALLING SEQUENCE: BLKSHIFT, UNIT, POS, [ DELTA, TO=TO, /NOZERO, ERRMSG=ERRMSG, BUFFERSIZE=BUFFERSIZE ] DESCRIPTION: BLKSHIFT moves a block of data forward or backward, to a new position in a data file. The old and new positions of the block can overlap safely. The new position can be specified with either the DELTA parameter, which gives the number of bytes to move forward (positive delta) or backward (negative delta); or the TO keyword, which give the new absolute starting position of the block. The block can be moved beyond the current end of file point, in which case the intervening gap is filled with zeros (optionally). The gap left at the old position of the block is also optionally zero-filled. If a set of data up to the end of the file is being moved forward (thus making the file smaller) then the file is truncated at the new end.using TRUNCATE_LUN. INPUTS: UNIT - a logical unit number, opened for reading and writing. POS - POS[0] is the position of the block in the file, in bytes, before moving. POS[1], if present, is the size of the block in bytes. If POS[1] is not given, then the block is from POS[0] to the end of the file. DELTA - the (optional) offset in bytes between the old and new positions, from the start of the block. Positive values indicate moving the data forward (toward the end of file), and negative values indicate moving the data backward (toward the beginning of the file). One of DELTA and TO must be specified; DELTA overrides the TO keyword. Attempts to move the block beyond the end of the file will succeed. A block can never be moved beyond the beginning of the file; it will be moved to the beginning instead. KEYWORD PARAMETERS: TO - the absolute file offset in bytes for the new start of the block. One of DELTA and TO must be specified; DELTA overrides the TO keyword. /NOZERO - if set, then newly created gaps will not be explicitly zeroed. Note that in same systems (e.g. MacOS) the gaps will always be zeroed whether or not /NOZERO is set. ERRMSG - If defined and passed, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. BLKSHIFT, UNIT, POS, DElTA, ERRMSG=ERRMSG, ... IF ERRMSG NE '' THEN ... BUFFERSIZE - the maximum buffer size for transfers, in bytes. Larger values of this keyword impose larger memory requirements on the application; smaller values will lead to more transfer operations. Default: 32768 (bytes) MODIFICATION HISTORY: Written, CM, Apr 2000 Documented and re-written, CM, 20 Jul 2000 Renamed from FXSHIFT to BLKSHIFT, CM, 21 Jul 2000 Documentation, CM, 12 Dec 2002 Truncate if moving data block forward from the end of file using TRUNCATE_LUN W. Landsman Feb. 2005 Assume since V5.5, remove VMS support W. Landsman Sep 2006 Assume since V5.6, TRUNCATE_LUN available W. Landsman Sep 2006 MacOS can point beyond EOF W. Landsman Aug 2009
(See $IDLUTILS_DIR/goddard/pro/misc/blkshift.pro)
BOOST_ARRAY
NAME: BOOST_ARRAY PURPOSE: Append one array onto a destination array EXPLANATION: Add array APPEND to array DESTINATION, allowing the dimensions of DESTINATION to adjust to accommodate it. If both input arrays have the same number of dimensions, then the output array will have one additional dimension. Otherwise, the last dimension of DESTINATION will be incremented by one. CATEGORY: Utility CALLING SEQUENCE: BOOST_ARRAY, DESTINATION, APPEND INPUT: DESTINATION = Array to be expanded. APPEND = Array to append to DESTINATION. OUTPUTS: DESTINATION = Expanded output array. RESTRICTIONS: DESTINATION and APPEND have to be either both of type string or both of numerical types. APPEND cannot have more dimensions than DESTINATION. MODIFICATION HISTOBY: Written Aug'88 (DMZ, ARC) Modified Sep'89 to handle byte arrays (DMZ) Modifed to version 2, Paul Hick (ARC), Feb 1991 Removed restriction to 2D arrays, William Thompson (ARC), Feb 1992. Converted to IDL V5.0 W. Landsman September 1997
(See $IDLUTILS_DIR/goddard/pro/misc/boost_array.pro)
BOXAVE
NAME: BOXAVE PURPOSE: Box-average a 1 or 2 dimensional array. EXPLANATION: This procedure differs from the intrinsic REBIN function in the follow 2 ways: (1) the box size parameter is specified rather than the output array size (2) for INTEGER arrays, BOXAVE computes intermediate steps using REAL*4 (or REAL*8 for 64bit integers) arithmetic. This is considerably slower than REBIN but avoids integer truncation CALLING SEQUENCE: result = BOXAVE( Array, Xsize,[ Ysize ] ) INPUTS: ARRAY - Two dimensional input Array to be box-averaged. Array may be one or 2 dimensions and of any type except character. OPTIONAL INPUTS: XSIZE - Size of box in the X direction, over which the array is to be averaged. If omitted, program will prompt for this parameter. YSIZE - For 2 dimensional arrays, the box size in the Y direction. If omitted, then the box size in the X and Y directions are assumed to be equal OUTPUT: RESULT - Output array after box averaging. If the input array has dimensions XDIM by YDIM, then RESULT has dimensions XDIM/NBOX by YDIM/NBOX. The type of RESULT is the same as the input array. However, the averaging is always computed using REAL arithmetic, so that the calculation should be exact. If the box size did not exactly divide the input array, then then not all of the input array will be boxaveraged. PROCEDURE: BOXAVE boxaverages all points simultaneously using vector subscripting NOTES: If im_int is a 512 x 512 integer array, then the two statements IDL> im = fix(round(rebin(float(im_int), 128, 128))) IDL> im = boxave( im_int,4) give equivalent results. The use of REBIN is faster, but BOXAVE is is less demanding on virtual memory, since one does not need to make a floating point copy of the entire array. REVISION HISTORY: Written, W. Landsman, October 1986 Call REBIN for REAL*4 and REAL*8 input arrays, W. Landsman Jan, 1992 Removed /NOZERO in output array definition W. Landsman 1995 Fixed occasional integer overflow problem W. Landsman Sep. 1995 Allow unsigned data types W. Landsman Jan. 2000 Assume since V5.4, Allow 64bit integers W. Landsman Apr 2006
(See $IDLUTILS_DIR/goddard/pro/image/boxave.pro)
BPRECESS
NAME: BPRECESS PURPOSE: Precess positions from J2000.0 (FK5) to B1950.0 (FK4) EXPLANATION: Calculates the mean place of a star at B1950.0 on the FK4 system from the mean place at J2000.0 on the FK5 system. CALLING SEQUENCE: bprecess, ra, dec, ra_1950, dec_1950, [ MU_RADEC = , PARALLAX = RAD_VEL =, EPOCH = ] INPUTS: RA,DEC - Input J2000 right ascension and declination in *degrees*. Scalar or N element vector OUTPUTS: RA_1950, DEC_1950 - The corresponding B1950 right ascension and declination in *degrees*. Same number of elements as RA,DEC but always double precision. OPTIONAL INPUT-OUTPUT KEYWORDS MU_RADEC - 2xN element double precision vector containing the proper motion in seconds of arc per tropical *century* in right ascension and declination. PARALLAX - N_element vector giving stellar parallax (seconds of arc) RAD_VEL - N_element vector giving radial velocity in km/s The values of MU_RADEC, PARALLAX, and RADVEL will all be modified upon output to contain the values of these quantities in the B1950 system. The parallax and radial velocity will have a very minor influence on the B1950 position. EPOCH - scalar giving epoch of original observations, default 2000.0d This keyword value is only used if the MU_RADEC keyword is not set. NOTES: The algorithm is taken from the Explanatory Supplement to the Astronomical Almanac 1992, page 186. Also see Aoki et al (1983), A&A, 128,263 BPRECESS distinguishes between the following two cases: (1) The proper motion is known and non-zero (2) the proper motion is unknown or known to be exactly zero (i.e. extragalactic radio sources). In this case, the reverse of the algorithm in Appendix 2 of Aoki et al. (1983) is used to ensure that the output proper motion is exactly zero. Better precision can be achieved in this case by inputting the EPOCH of the original observations. The error in using the IDL procedure PRECESS for converting between B1950 and J1950 can be up to 12", mainly in right ascension. If better accuracy than this is needed then BPRECESS should be used. An unsystematic comparison of BPRECESS with the IPAC precession routine (http://nedwww.ipac.caltech.edu/forms/calculator.html) always gives differences less than 0.15". EXAMPLE: The SAO2000 catalogue gives the J2000 position and proper motion for the star HD 119288. Find the B1950 position. RA(2000) = 13h 42m 12.740s Dec(2000) = 8d 23' 17.69'' Mu(RA) = -.0257 s/yr Mu(Dec) = -.090 ''/yr IDL> mu_radec = 100D* [ -15D*.0257, -0.090 ] IDL> ra = ten(13, 42, 12.740)*15.D IDL> dec = ten(8, 23, 17.69) IDL> bprecess, ra, dec, ra1950, dec1950, mu_radec = mu_radec IDL> print, adstring(ra1950, dec1950,2) ===> 13h 39m 44.526s +08d 38' 28.63" REVISION HISTORY: Written, W. Landsman October, 1992 Vectorized, W. Landsman February, 1994 Treat case where proper motion not known or exactly zero November 1994 Handling of arrays larger than 32767 Lars L. Christensen, march, 1995 Fixed bug where A term not initialized for vector input W. Landsman February 2000 Use V6.0 notation W. Landsman Mar 2011
(See $IDLUTILS_DIR/goddard/pro/astro/bprecess.pro)
BREAK_PATH()
NAME: BREAK_PATH() PURPOSE: Breaks up a path string into its component directories. CALLING SEQUENCE: Result = BREAK_PATH( PATHS [ /NoCurrent]) INPUTS: PATHS = A string containing one or more directory paths. The individual paths are separated by commas, although in UNIX, colons can also be used. In other words, PATHS has the same format as !PATH, except that commas can be used as a separator regardless of operating system. A leading $ can be used in any path to signal that what follows is an environmental variable, but the $ is not necessary. Environmental variables can themselves contain multiple paths. OUTPUT: The result of the function is a string array of directories. Unless the NOCURRENT keyword is set, the first element of the array is always the null string, representing the current directory. All the other directories will end in the correct separator character for the current operating system. OPTIONAL INPUT KEYWORD: /NOCURRENT = If set, then the current directory (represented by the null string) will not automatically be prepended to the output. PROCEDURE CALLS: None. REVISION HISTORY: Version 1, William Thompson, GSFC, 6 May 1993. Added IDL for Windows compatibility. Version 2, William Thompson, GSFC, 16 May 1995 Added keyword NOCURRENT Version 3, William Thompson, GSFC, 29 August 1995 Modified to use OS_FAMILY Version 4, Zarro, GSFC, 4 August 1997 Added trim to input Fix directory character on Macintosh system A. Ferro February 2000 Use STRSPLIT instead of STR_SEP() W. Landsman July 2002 Remove VMS support W. Landsman September 2006
(See $IDLUTILS_DIR/goddard/pro/misc/break_path.pro)
BSORT
NAME: BSORT PURPOSE: Function to sort data into ascending order, like a simple bubble sort. EXPLANATION: Original subscript order is maintained when values are equal (FIFO). (This differs from the IDL SORT routine alone, which may rearrange order for equal values) A faster algorithm (radix sort) for numeric data is available at http://idldatapoint.com/2012/04/19/an-lsd-radix-sort-algorithm-in-idl/ CALLING SEQUENCE: result = bsort( array, [ asort, /INFO, /REVERSE ] ) INPUT: Array - array to be sorted OUTPUT: result - sort subscripts are returned as function value OPTIONAL OUTPUT: Asort - sorted array OPTIONAL KEYWORD INPUTS: /REVERSE - if this keyword is set, and non-zero, then data is sorted in descending order instead of ascending order. /INFO = optional keyword to cause brief message about # equal values. HISTORY written by F. Varosi Oct.90: uses WHERE to find equal clumps, instead of looping with IF ( EQ ). compatible with string arrays, test for degenerate array 20-MAY-1991 JKF/ACC via T AKE- return indexes if the array to be sorted has all equal values. Aug - 91 Added REVERSE keyword W. Landsman Always return type LONG W. Landsman August 1994 Converted to IDL V5.0 W. Landsman September 1997
(See $IDLUTILS_DIR/goddard/pro/misc/bsort.pro)
CALZ_UNRED
NAME: CALZ_UNRED PURPOSE: Deredden a galaxy spectrum using the Calzetti et al. (2000) recipe EXPLANATION: Calzetti et al. (2000, ApJ 533, 682) developed a recipe for dereddening the spectra of galaxies where massive stars dominate the radiation output, valid between 0.12 to 2.2 microns. (CALZ_UNRED extrapolates between 0.12 and 0.0912 microns.) CALLING SEQUENCE: CALZ_UNRED, wave, flux, ebv, [ funred, R_V = ] INPUT: WAVE - wavelength vector (Angstroms) FLUX - calibrated flux vector, same number of elements as WAVE If only 3 parameters are supplied, then this vector will updated on output to contain the dereddened flux. EBV - color excess E(B-V), scalar. If a negative EBV is supplied, then fluxes will be reddened rather than deredenned. Note that the supplied color excess should be that derived for the stellar continuum, EBV(stars), which is related to the reddening derived from the gas, EBV(gas), via the Balmer decrement by EBV(stars) = 0.44*EBV(gas) OUTPUT: FUNRED - unreddened flux vector, same units and number of elements as FLUX. FUNRED values will be zeroed outside valid domain Calz_unred (0.0912 - 2.2 microns). OPTIONAL INPUT KEYWORD: R_V - Ratio of total to selective extinction, default = 4.05. Calzetti et al. (2000) estimate R_V = 4.05 +/- 0.80 from optical -IR observations of 4 starbursts. EXAMPLE: Estimate how a flat galaxy spectrum (in wavelength) between 1200 A and 3200 A is altered by a reddening of E(B-V) = 0.1. IDL> w = 1200 + findgen(40)*50 ;Create a wavelength vector IDL> f = w*0 + 1 ;Create a "flat" flux vector IDL> calz_unred, w, f, -0.1, fnew ;Redden (negative E(B-V)) flux vector IDL> plot,w,fnew NOTES: Use the 4 parameter calling sequence if you wish to save the original flux vector. PROCEDURE CALLS: POLY() REVISION HISTORY: Written W. Landsman Raytheon ITSS December, 2000
(See $IDLUTILS_DIR/goddard/pro/astro/calz_unred.pro)
CCM_UNRED
NAME: CCM_UNRED PURPOSE: Deredden a flux vector using the CCM 1989 parameterization EXPLANATION: The reddening curve is that of Cardelli, Clayton, and Mathis (1989 ApJ. 345, 245), including the update for the near-UV given by O'Donnell (1994, ApJ, 422, 158). Parameterization is valid from the IR to the far-UV (3.5 microns to 0.1 microns). Users might wish to consider using the alternate procedure FM_UNRED which uses the extinction curve of Fitzpatrick (1999). CALLING SEQUENCE: CCM_UNRED, wave, flux, ebv, funred, [ R_V = ] or CCM_UNRED, wave, flux, ebv, [ R_V = ] INPUT: WAVE - wavelength vector (Angstroms) FLUX - calibrated flux vector, same number of elements as WAVE If only 3 parameters are supplied, then this vector will updated on output to contain the dereddened flux. EBV - color excess E(B-V), scalar. If a negative EBV is supplied, then fluxes will be reddened rather than deredenned. OUTPUT: FUNRED - unreddened flux vector, same units and number of elements as FLUX OPTIONAL INPUT KEYWORD R_V - scalar specifying the ratio of total selective extinction R(V) = A(V) / E(B - V). If not specified, then R_V = 3.1 Extreme values of R(V) range from 2.75 to 5.3 EXAMPLE: Determine how a flat spectrum (in wavelength) between 1200 A and 3200 A is altered by a reddening of E(B-V) = 0.1. Assume an "average" reddening for the diffuse interstellar medium (R(V) = 3.1) IDL> w = 1200 + findgen(40)*50 ;Create a wavelength vector IDL> f = w*0 + 1 ;Create a "flat" flux vector IDL> ccm_unred, w, f, -0.1, fnew ;Redden (negative E(B-V)) flux vector IDL> plot,w,fnew NOTES: (1) The CCM curve shows good agreement with the Savage & Mathis (1979) ultraviolet curve shortward of 1400 A, but is probably preferable between 1200 and 1400 A. (2) Many sightlines with peculiar ultraviolet interstellar extinction can be represented with a CCM curve, if the proper value of R(V) is supplied. (3) Curve is extrapolated between 912 and 1000 A as suggested by Longo et al. (1989, ApJ, 339,474) (4) Use the 4 parameter calling sequence if you wish to save the original flux vector. (5) Valencic et al. (2004, ApJ, 616, 912) revise the ultraviolet CCM curve (3.3 -- 8.0 um-1). But since their revised curve does not connect smoothly with longer and shorter wavelengths, it is not included here. REVISION HISTORY: Written W. Landsman Hughes/STX January, 1992 Extrapolate curve for wavelengths between 900 and 1000 A Dec. 1993 Use updated coefficients for near-UV from O'Donnell Feb 1994 Allow 3 parameter calling sequence April 1998 Converted to IDLV5.0 April 1998
(See $IDLUTILS_DIR/goddard/pro/astro/ccm_unred.pro)
CENTERTLB
NAME: CENTERTLB PURPOSE: This is a utility routine to position a widget program on the display at an arbitrary location. By default the widget is centered on the display. AUTHOR: FANNING SOFTWARE CONSULTING David Fanning, Ph.D. 1645 Sheely Drive Fort Collins, CO 80526 USA Phone: 970-221-0438 E-mail: david@idlcoyote.com Coyote's Guide to IDL Programming: http://www.idlcoyote.com CATEGORY: Utilities CALLING SEQUENCE: CenterTLB, tlb, [x, y, /NOCENTER, /DEVICE, CENTERONTLB=wOtherTLBID] REQUIRED INPUTS: tlb: The top-level base identifier of the widget program. This must be a valid widget ID. OPTIONAL INPUTS: x: Set this equal to a normalized position for the center of the widget as measured from the left-hand side of the screen. The default value is 0.5 (the center) Setting this equal to 1.0 places the widget at the far right-hand side of the screen. y: Set this equal to a normalized position for the center of the widget as measured from the bottom of the screen. The default value is 0.5 (the center) Setting this equal to 1.0 places the widget at the top of the screen. KEYWORDS: DEVICE: Normally, the x and y parameters are specified in normalized coordinates. If this keyword is set, they are taken to be in DEVICE coordinates. NOCENTER: By default, the center of the widget is positioned at the location specified by the x and y parameters. If NOCENTER is set to a non-zero value, then the upper left corner of the widget is postioned at the specifed location. CENTERONTLB: If provided, the center of the widget is positioned at the center of the widget whose ID is provided here. PROCEDURE: The program should be called after all the widgets have been created, but just before the widget hierarchy is realized. It uses the top-level base geometry along with the display size to calculate offsets for the top-level base that will center the top-level base on the display. COMMENT: Regardless of the values set for x, y and NOCENTER, the widget is not permitted to run off the display. MODIFICATION HISTORY: Written by: Dick Jackson, 12 Dec 98. Modified to use device-independent Get_Screen_Size function. 31 Jan 2000. DWF. Added x, y, NOCENTER and run-off protection. 26 Jan 2001. BT. Added a maximum value of 1280 for X screen size. This helps center the widget on a single monitor when using dual monitor settings with some graphics cards. 3 Feb 2003. DWF. Added DEVICE keyword. 4 January 2006. DWF. Added CenterOnTLB keyword. 7 March 2011. DJ.
(See $IDLUTILS_DIR/goddard/pro/coyote/centertlb.pro)
CGAXIS
Provides a device-independent and color-model-independent way to draw an axis into a graphics window. It is a wrapper to the AXIS command. The program requires the `Coyote Library <http://www.idlcoyote.com/documents/programs.php>` to be installed on your machine. :Categories: Graphics :Params: xloc: in, optional, type=depends The X location of the axis. yloc: in, optional, type=depends The Y location of the axis. zloc: in, optional, type=depends The Z location of the axis. :Keywords: charsize: in, optional, type=float, default=cgDefCharSize() The character size for axes annotations. Uses cgDefCharSize to select default character size, unless !P.Charsize is set, in which case !P.Charsize is always used. color: in, optional, type=string/integer/long The color of the text. Color names are those used with cgColor. By default, "black", unless the upper-right hand pixel in the display is black, then "white". data: in, optional, type=boolean Set this keyword to indicate xloc and yloc are in data coordinates. Data coordinates are the default, unless DEVICE or NORMAL is set. device: in, optional, type=boolean Set this keyword to indicate xloc and yloc are in device coordinates. font: in, optional, type=integer, default=!P.Font The type of font desired. By default, !P.Font. normal: in, optional, type=boolean Set this keyword to indicate xloc and yloc are in normalized coordinates. save: in, optional, type=boolean Set this keyword to save the scaling parameters set by the axis for subsequent use. t3d: in, optional, type=boolean, default=0 Set this keyword to rotate the axis is the 3D data space set up with !P.T. title: in, optional, type=string, default="" The title or annotation that appears on the axis. window: in, optional, type=boolean Set this keyword to add the command to the in the current cgWindow application. xaxis: in, optional, type=integer, default=0 If set to 0, the axis is drawn under the plot with the tick marks pointing up; if set to 1, the axis is drawn on top of the plot with the tick marks pointing down. xlog: in, optional, type=boolean, default=0 Set this keyword to specify a logarithmic axis type. xtitle: in, optional, type=string An alternative way to set the `Title` keyword for X axes. Use `Title` instead. yaxis: in, optional, type=integer, default=0 If set to 0, the axis is drawn on the left of the plot with the tick marks pointing to the right. If set to 1, the axis is drawn on the right of the plot with the tick marks pointing to the left. ylog: in, optional, type=boolean, default=0 Set this keyword to specify a logarithmic axis type. ynozero: in, optional, type=boolean, default=0 Set this keyword to prevent the Y axis from starting at 0. ytitle: in, optional, type=string An alternative way to set the `Title` keyword for Y axes. Use `Title` instead. zaxis: in, optional, type=integer, default=0 Set to 0-3 to position the Z axis in various locatons. See the AXIS documentation. zlog: in, optional, type=boolean, default=0 Set this keyword to specify a logarithmic axis type. ztitle: in, optional, type=string An alternative way to set the `Title` keyword for Z axes. Use `Title` instead. _ref_extra: in, optional Any keywords appropriate for the AXIS command. :Examples: Used like the IDL AXIS command:: IDL> cgPlot, cgDemoData(1), YStyle=8, Position=[0.1, 0.1, 0.85, 0.9], /Window IDL> cgAxis, /YAxis, Color='red', YRange=[-500, 500], /Save, /Window :Author: FANNING SOFTWARE CONSULTING:: David W. Fanning 1645 Sheely Drive Fort Collins, CO 80526 USA Phone: 970-221-0438 E-mail: david@idlcoyote.com Coyote's Guide to IDL Programming: http://www.idlcoyote.com :History: Change History:: Written, 25 Janauray 2011. DWF. Modified error handler to restore the entry decomposition state if there is an error. 17 March 2011. DWF Modifed the way I am handling brain dead AXIS command. 30 May 2011. DWF. Modified to use cgDefaultColor for default color selection. 24 Dec 2011. DWF. Added T3D keyword. 1 March 2012. DWF. :Copyright: Copyright (c) 2011, Fanning Software Consulting, Inc.
(See $IDLUTILS_DIR/goddard/pro/coyote/cgaxis.pro)
CGCOLORFILL
Provides a device-independent and color-model-independent way to fill a polygon with a particular color. This is a wrapper to the PolyFill command in IDL. The program requires the `Coyote Library <http://www.idlcoyote.com/documents/programs.php>` to be installed on your machine. :Categories: Graphics :Params: x: in, required, type=number A vector argument providing the X coordinates of the points to be connected. The vector must contain at least three elements. If only one argument is specified, X must be an array of either two or three vectors (i.e., (2,*) or (3,*)). In this special case, the vector X[0,*] specifies the X values, X[1,*] specifies Y, and X[2,*] contain the Z values. y: in, required, type=number A vector argument providing the Y coordinates of the points to be connected. Y must contain at least three elements. z: in, optional, type=number An optional vector argument providing the Z coordinates of the points to be connected. Z must contain at least three elements. :Keywords: color: in, optional, type=string/integer/long, default='rose' The name of the fill color. Color names are those used with cgColor. This value can also be a long integer or an index into the current color table. device: in, optional, type=boolean, default=0 Set to indicate the polygon vertices are in device coordinates. normal: in, optional, type=boolean, default=0 Set to indicate the polygon vertices are in normalized coordinates. window: in, optional, type=boolean, default=0 Set this keyword to add the command to the current cgWindow application. _ref_extra: in, optional, type=appropriate Any other keywords to the IDL POLYFILL command may be used. :Examples: Used like the IDL Polyfill command:: IDL> cgColorFill, [0.25, 0.25, 0.75, 0.75, 0.25], [0.25, 0.75, 0.75, 0.25, 0.25], $ /NORMAL, COLOR='blue' :Author: FANNING SOFTWARE CONSULTING:: David W. Fanning 1645 Sheely Drive Fort Collins, CO 80526 USA Phone: 970-221-0438 E-mail: david@idlcoyote.com Coyote's Guide to IDL Programming: http://www.idlcoyote.com :History: Change History:: Written, 24 December 2010. DWF. In some cases, I was turning BYTE values to strings without converting to INTEGERS first. 30 Dec 2010. DWF. Moved setting to decomposed color before color selection process to avoid PostScript background problems when passed 24-bit color integers. 12 Jan 2011. DWF. Added WINDOW keyword. 24 Jan 2011. DWF. Modified error handler to restore the entry decomposition state if there is an error. 17 March 2011. DWF Modified to use cgDefaultColor for default color selection. 24 Dec 2011. DWF. :Copyright: Copyright (c) 2010, Fanning Software Consulting, Inc.
(See $IDLUTILS_DIR/goddard/pro/coyote/cgcolorfill.pro)
CGCOLOR[1]
The purpose of this function is to obtain drawing colors by name and in a device/decomposition independent way. The color names and values may be read in as a file, or 192 color names and values are supplied with the program. These colors were obtained from the file rgb.txt, found on most X-Window distributions, and from colors in the `Brewer color tables <http://colorbrewer2.org/>`. Representative colors were chosen from across the color spectrum. If the color names '0', '1', '2', ..., '255' are used, they will correspond to the colors in the current color table in effect at the time the `cgColor` program is called. The program requires the `Coyote Library <http://www.idlcoyote.com/documents/programs.php>` to be installed on your machine. :Categories: Graphics :Examples: To get drawing colors in a device-decomposed independent way:: axisColor = cgColor("Green", !D.Table_Size-2) backColor = cgColor("Charcoal", !D.Table_Size-3) dataColor = cgColor("Yellow", !D.Table_Size-4) Plot, Findgen(11), Color=axisColor, Background=backColor, /NoData OPlot, Findgen(11), Color=dataColor To set the viewport color in object graphics:: theView = Obj_New('IDLgrView', Color=cgColor('Charcoal', /Triple)) To change the viewport color later:: theView->SetProperty, Color=cgColor('Antique White', /Triple) To load the drawing colors "red", "green", and "yellow" at indices 100-102, type this:: IDL> TVLCT, cgColor(["red", "green", "yellow"], /Triple), 100 To interactively choose a color, set the SELECTCOLOR keyword:: IDL> color = cgColor(/SelectColor) The PickColorName program is a good way to learn the names of the colors available:: IDL> color = PickColorName() :Author: FANNING SOFTWARE CONSULTING:: David W. Fanning 1645 Sheely Drive Fort Collins, CO 80526 USA Phone: 970-221-0438 E-mail: david@idlcoyote.com Coyote's Guide to IDL Programming: http://www.idlcoyote.com :History: Change History:: Written by: David W. Fanning Modified FSC_COLOR to create cgColor 9 February 2011. DWF. Modified to allow a three-element color triple to be used in place of the color name parameter. This allows one user-defined color to be used. 4 Dec 2011. DWF. Modified to allow byte and 16-bit integer values to be used to specify colors in the current color table. 5 Dec 2011. DWF. Modified to allow the "opposite" pixel to be determined in the Z-graphics buffer. 24 Dec 2011. DWF. Modified the code to handle long integers depending on the current color mode and the number of values passed in. 10 January 2012. DWF. Made sure the return values are BYTES not INTEGERS, in cases where this is expected. 10 Jan 2012. DWF. Added "Background" as a color name. The opposite of "Opposite". 1 Feb 2012. DWF. When returning a vector of color values, now making sure to return a byte array if in indexed color mode. 27 Feb 2012. DWF. :Copyright: Copyright (c) 2009-2012, Fanning Software Consulting, Inc.
(See $IDLUTILS_DIR/goddard/pro/coyote/cgcolor.pro)
CGCOLOR[2]
+ This function accepts a [red, green, blue] triple that describes a particular color and returns a 24-bit long integer that is equivalent to (can be decomposed into) that color. :Params: color: in, required, type=byte A three-element byte array containing the color triple. The triple can be either a row or column vector of three elements or it can be an N-by-3 array of color triples.
(See $IDLUTILS_DIR/goddard/pro/coyote/cgcolor.pro)
CGCOLOR[3]
The purpose of this function is to obtain drawing colors by name and in a device/decomposition independent way. :Returns: The return value depends on the color mode in effect at the time the program is called and which keyword is used with the program. In normal operation, if the graphics device is using indexed color mode, the program will load a color at a unique (or specified) index and return that index number. If the graphics device is using decomposed color mode, the program will create a 24-bit color value that can be used to specify the particular color desired. In this case, no color is loaded in the color table. This is the preferred mode for working with colors in IDL. :Params: theColour: required, optional, type=varies Normally the name of the color desired. However, this can also be a string index number (e.g., '215') or a byte or short integer value (e.g, 215B or 215S). If this is the case, the color in the current color table at this index number is used for the color that is returned. The value may also be a vector of color names. The color may also be a three-element byte or integer array specifying a user-defined color triple. Only one color triple is allowed. To see a list of the color names available set the NAMES keyword. Colors available are these:: Active Almond Antique White Aquamarine Beige Bisque Black Blue Blue Violet Brown Burlywood Cadet Blue Charcoal Chartreuse Chocolate Coral Cornflower Blue Cornsilk Crimson Cyan Dark Goldenrod Dark Gray Dark Green Dark Khaki Dark Orchid Dark Red Dark Salmon Dark Slate Blue Deep Pink Dodger Blue Edge Face Firebrick Forest Green Frame Gold Goldenrod Gray Green Green Yellow Highlight Honeydew Hot Pink Indian Red Ivory Khaki Lavender Lawn Green Light Coral Light Cyan Light Gray Light Salmon Light Sea Green Light Yellow Lime Green Linen Magenta Maroon Medium Gray Medium Orchid Moccasin Navy Olive Olive Drab Orange Orange Red Orchid Pale Goldenrod Pale Green Papaya Peru Pink Plum Powder Blue Purple Red Rose Rosy Brown Royal Blue Saddle Brown Salmon Sandy Brown Sea Green Seashell Selected Shadow Sienna Sky Blue Slate Blue Slate Gray Snow Spring Green Steel Blue Tan Teal Text Thistle Tomato Turquoise Violet Violet Red Wheat White Yellow Here are the Brewer color names:: WT1 WT2 WT3 WT4 WT5 WT6 WT7 WT8 TAN1 TAN2 TAN3 TAN4 TAN5 TAN6 TAN7 TAN8 BLK1 BLK2 BLK3 BLK4 BLK5 BLK6 BLK7 BLK8 GRN1 GRN2 GRN3 GRN4 GRN5 GRN6 GRN7 GRN8 BLU1 BLU2 BLU3 BLU4 BLU5 BLU6 BLU7 BLU8 ORG1 ORG2 ORG3 ORG4 ORG5 ORG6 ORG7 ORG8 RED1 RED2 RED3 RED4 RED5 RED6 RED7 RED8 PUR1 PUR2 PUR3 PUR4 PUR5 PUR6 PUR7 PUR8 PBG1 PBG2 PBG3 PBG4 PBG5 PBG6 PBG7 PBG8 YGB1 YGB2 YGB3 YGB4 YGB5 YGB6 YGB7 YGB8 RYB1 RYB2 RYB3 RYB4 RYB5 RYB6 RYB7 RYB8 TG1 TG2 TG3 TG4 TG5 TG6 TG7 TG8 The color name "OPPOSITE" is also available. It chooses a color "opposite" to the color of the pixel in the upper-right corner of the display, if a window is open. Otherwise, this color is "black" in PostScript and "white" everywhere else. The color OPPOSITE is used if this parameter is absent or a color name is mis-spelled. The color name "BACKGROUND" can similarly be used to select the color of the pixel in the upper-right corner of the display, if a window is open. colorindex: in, optional, type=byte The color table index where the color should be loaded. Colors are loaded into the color table only if using indexed color mode in the current graphics device. If this parameter is missing, the color will be loaded at a unique color index number, if necessary. :Keywords: allcolors: in, optional, type=boolean, default=0 Set this keyword to return indices, or 24-bit values, or color triples, for all the known colors, instead of for a single color. brewer: in, optional, type=boolean, default=0 An obsolete keyword. If used, only Brewer colors are loaded into the color vectors internally. cancel: out, optional, type=boolean, default=0 This keyword is always set to 0, unless that SELECTCOLOR keyword is used. Then it will correspond to the value of the CANCEL output keyword in PICKCOLORNAME. check_connection: in, optional, type=boolean, default=0 An obsolete keyword now completely ignored. colorstructure: out, optional, type=structure This output keyword (if set to a named variable) will return a structure in which the fields will be the known color names (without spaces) and the values of the fields will be either color table index numbers or 24-bit color values. If you have specified a vector of color names, then this will be a structure containing just those color names as fields. decomposed: in, optional, type=boolean Set this keyword to 0 or 1 to force the return value to be a color table index or a 24-bit color value, respectively. This keyword is normally set by the color state of the current graphics device. filename: in, optional, type=string The name of an ASCII file that can be opened to read in color values and color names. There should be one color per row in the file. Please be sure there are no blank lines in the file. The format of each row should be:: redValue greenValue blueValue colorName Color values should be between 0 and 255. Any kind of white-space separation (blank characters, commas, or tabs) are allowed. The color name should be a string, but it should NOT be in quotes. A typical entry into the file would look like this:: 255 255 0 Yellow names: in, optional, type=boolian, default=0 If this keyword is set, the return value of the function is a string array containing the names of the colors. These names would be appropriate, for example, in building a list widget with the names of the colors. If the NAMES keyword is set, the COLOR and INDEX parameters are ignored. ncolors: out, optional, type=integer Returns the number of colors that cgColor "knows" about. Currently ncolors=193. nodisplay: in, optional, type=boolean, default=0 An obsolete keyword, now totally ignored. row: in, optional, type=boolean If this keyword is set, the return value of the function when the TRIPLE keyword is set is returned as a row vector, rather than as the default column vector. This is required, for example, when you are trying to use the return value to set the color for object graphics objects. This keyword is completely ignored, except when used in combination with the TRIPLE keyword. selectcolor: in, optional, type=boolean Set this keyword if you would like to select the color name with the PICKCOLORNAME program. Selecting this keyword automaticallys sets the INDEX positional parameter. If this keyword is used, any keywords appropriate for PICKCOLORNAME can also be used. If this keyword is used, the first positional parameter can be a color name that will appear in the SelectColor box. triple: in, optional, type=boolean Setting this keyword will force the return value of the function to always be a color triple, regardless of color decomposition state or visual depth of the machine. The value will be a three-element column vector unless the ROW keyword is also set. _ref_extra: in, optional Any keyword parameter appropriate for PICKCOLORNAME can be used. These include BOTTOM, COLUMNS, GROUP_LEADER, INDEX, and TITLE.
(See $IDLUTILS_DIR/goddard/pro/coyote/cgcolor.pro)
CGCONTOUR
The purpose of cgContour is to create a wrapper for the traditional IDL graphics command, Contour. The Contour command has a number of deficiencies that make it difficult to use in a modern computing environment. cgContour corrects these deficiencies and allows the user to produce traditional contour plots in a device and machine independent manner. The program requires the `Coyote Library <http://www.idlcoyote.com/documents/programs.php>` to be installed on your machine. :Categories: Graphics :Params: data: in, required, type=any A one- or two-dimensional array containing the values that make up the contour surface. x: in, optional, type=any A vector or two-dimensional array specifying the X coordinates for the contour surface. y: in, optional, type=any A vector or two-dimensional array specifying the Y coordinates for the contour surface. :Keywords: addcmd: in, optional, type=boolean, default=0 Set this keyword to add the command to an cgWindow. Setting this keyword automatically sets the WINDOW keyword, but the command does not erase the graphics window as it would normally. axiscolor: in, optional, type=string/integer, default='opposite' If this keyword is a string, the name of the axis color. Otherwise, the keyword is assumed to be a color index into the current color table. axescolor: in, optional, type=string/integer Provisions for bad spellers. background: in, optional, type=string/integer, default='background' If this keyword is a string, the name of the background color. Otherwise, the keyword is assumed to be a color index into the current color table. c_colors: in, optional, type=integer/string vector Set to the index values of the contour colors or to named colors. Must contain the same number of colors as the number of requested contour levels. c_labels: in, optional, type=integer A vector that specifies which contour levels to label. If used, the LABEL keyword is ignored. c_charsize: in, optional, type=float The character size of the annotations used on the contour lines themselves. By default, 75% of `Charsize`. cell_fill: in, optional, type=boolean, default=0 Set to indicate filled contours should be created using the "cell fill" method. This keyword should always be set if displaying filled contours on map projections or if missing data is present in the data you are contouring. charsize: in, optional, type=float, default=cgDefCharSize() The character size for axes annotations. Uses cgDefCharSize to select default character size, unless !P.Charsize is set, in which case !P.Charsize is always used. color: in, optional, type=string/integer, default='black' If this keyword is a string, the name of the data color. By default, same as AXISCOLOR. Otherwise, the keyword is assumed to be a color index into the current color table. font: in, optional, type=integer, default=!P.Font The type of font desired for axis annotation. fill: in, optional, type=boolean, default=0 Set to indicate filled contours should be created. irregular: in, optional, type=boolean If this keyword is set, the data, x, and y input parameters are taken to be irregularly gridded data, the the data is gridded for use in the contour plot using the Triangulate and Trigrid method. The resolution of the gridded output is set by the RESOLUTION keyword. label: in, optional, type=integer, default=1 An number that tells how to label contour levels. A 0 means no contour levels are labelled. A 1 (the default) means all contour levels are labelled. A 2 means label every 2nd contour level is labelled. A 3 means every 3rd contour level is labelled, and so on. layout: in, optional, type=intarr(3) This keyword specifies a grid with a graphics window and determines where the graphic should appear. The syntax of LAYOUT is three numbers: [ncolumns, nrows, location]. The grid is determined by the number of columns (ncolumns) by the number of rows (nrows). The location of the graphic is determined by the third number. The grid numbering starts in the upper left (1) and goes sequentually by column and then by row. levels: in, optional, type=any A vector of data levels to contour. If used, NLEVELS is ignored. If missing, NLEVELS is used to construct N equally-spaced contour levels. map_object: in, optional, type=object If you are overplotting (OVERPLOT=1) on a map projection set up with Map_Proj_Init and using projected meter space, rather than lat/lon space, then you can use this keyword to provide a cgMap object that will allow you to convert the `x` and `y` grid parameters from longitude and latitude, respectively, to projected meter space before the contour is displayed. Note, you MUST pass the `x` and `y` grid parameters to cgContour if you are overplotting on a map projection. There is no checking to be sure these parameters are in the correct longitude and latitude range, respectively. missingvalue: in, optional, type=any Use this keyword to identify any missing data in the input data values. noclip: in, optional, type=boolean, default=0 Normally, the plot is clipped to the axes boundaries. Setting this keyword prevents such clipping. Normally, this keyword is only used when there is a problem displaying contour plots in 3D space. nlevels: in, optional, type=integer, default=6 If the Contour plot LEVELS keyword is not used, this keyword will produce this number of equally spaced contour intervals. Unlike the Contour NLEVELS keyword, this keyword actually works! noerase: in, optional, type=boolean, default=0 Set this keyword to prevent the window from erasing the contents before displaying the contour plot. olevels: out, optional Set to a named variable to return the actual contour levels used in the program. Unfortunately, output variables cannot be returned if the cgContour command is being executed in a cgWindow. onimage: in, optional, type=boolean, default=0 If this keyword is set, and an image has been display previously with cgImage, then the contour plot will determine the location of the image in the display window and overplot itself onto that image. outcolor: in, optional, type=string, default='charcoal' The color of the contour lines when the `Outline` keyword is used. outfilename: in, optional, type=string If the `Output` keyword is set, the user will be asked to supply an output filename, unless this keyword is set to a non-null string. In that case, the value of this keyword will be used as the filename and there will be no dialog presented to the user. outline: in, optional, type=boolean, default=0 This keyword applies only if the `Fill` keyword is set. It will draw the contour lines on top of the filled contour. It draws the outline in the `OutColor`. output: in, optional, type=string, default="" Set this keyword to the type of output desired. Possible values are these:: 'PS' - PostScript file 'EPS' - Encapsulated PostScript file 'PDF' - PDF file 'BMP' - BMP raster file 'GIF' - GIF raster file 'JPEG' - JPEG raster file 'PNG' - PNG raster file 'TIFF' - TIFF raster file Or, you can simply set this keyword to the name of the output file, and the type of file desired will be determined by the file extension. If you use this option, the user will not be prompted to supply the name of the output file. All raster file output is created through PostScript intermediate files (the PostScript files will be deleted), so ImageMagick and Ghostview MUST be installed to produce anything other than PostScript output. (See cgPS2PDF and PS_END for details.) And also note that you should NOT use this keyword when doing multiple plots. The keyword is to be used as a convenient way to get PostScript or raster output for a single graphics command. Output parameters can be set with cgWindow_SetDefs. overplot: in, optional, type=boolean, default=0 Set this keyword to overplot the contours onto a previously established data coordinate system. palette: in, optional, type=byte A (256x3) color palette containing the RGB color vectors to use for coloring contours. Contour colors will be sampled from the color table palette into the number of contour levels required. If the palette is NOT 256 elements in length, then it is assumed that the length corresponds to the number of levels to be contoured. position: in, optional, type=float Set this keyword to a four-element [x0,y0,x1,y1] array giving the contour plot position in normalized coordinates. resolution: in, optional, type=integer array, default=[41\,41] If the IRREGULAR keyword is set, this keyword specifies the X and Y resolution in a two element integer array of the final gridded data that is sent to the contour plot. t3d: in, optional, type=boolean, default=0 Set this keyword to use the 3D axis rotation matrix in !P.T3D. traditional: in, optional, type=boolean, default=0 If this keyword is set, the traditional color scheme of a black background for graphics windows on the display is used and PostScript files always use a white background. window: in, optional, type=boolean, default=0 Set this keyword if you want to display the plot in a resizable graphics window. xstyle: in, optional, type=integer, default=1 If unused in the program, set to 1 to force exact axis scaling. xthick: in, optional, type=integer, default=1 The thickness of the X axis annotations. xticklen: in, optional, type=float, default=0.025 The length of the X tick marks. Set to a negative value to create outward facing tick marks. xticks: in, optional, type=integer The number of tick intervals on the X axis. xtickv: in, optional, type=string A vector of tick values to use with the tick marks. See IDL documentation for graphics keywords for additional information. ystyle: in, optional, type=integer, default=1 If unused in the program, set to 1 to force exact axis scaling. ythick: in, optional, type=integer, default=1 The thickness of the Y axis annotations. yticklen: in, optional, type=float, default=0.025 The length of the Y tick marks. Set to a negative value to create outward facing tick marks. yticks: in, optional, type=integer The number of tick intervals on the Y axis. ytickv: in, optional, type=string A vector of tick values to use with the tick marks. See IDL documentation for graphics keywords for additional information. _ref_extra: in, optional, type=any Any keyword appropriate for the IDL Contour command is allowed in the program. :Examples: Use as you would use the IDL CONTOUR command:: data = dist(51) cgContour, data LoadCT, 33 cgContour, data, /FILL cgContour, data, /OVERPLOT If you wish to overplot on top of an image, use the ONIMAGE keyword, rather than the OVERPLOT keyword: cgImage, data, /SCALE, XRANGE=[-10, 10], YRANGE=[-5,5], /AXES cgContour, data, /ONIMAGE See `Device Independent Contour Plots <http://www.idlcoyote.com/graphics_tips/cgcontour.html>' for additional examples. :Author: FANNING SOFTWARE CONSULTING:: David W. Fanning 1645 Sheely Drive Fort Collins, CO 80526 USA Phone: 970-221-0438 E-mail: david@idlcoyote.com Coyote's Guide to IDL Programming: http://www.idlcoyote.com :History: Change History:: Written, 11 November 2010. DWF. Restored the CELL_FILL keyword, which had been accidentally removed in the earlier version. 12 November 2010. DWF. Add the ability to specify the contour colors as color names. 16 November 2010. DWF. Now setting decomposition state by calling SetDecomposedState. 16 November 2010. DWF. Final color table restoration skipped in Z-graphics buffer. 17 November 2010. DWF. Background keyword now applies in PostScript file as well. 17 November 2010. DWF. Many changes after BACKGROUND changes to get !P.MULTI working again! 18 November 2010. DWF. Fixed a small problem with the OVERPLOT keyword. 18 Nov 2010. DWF. Changes so that color variables don't change type. 23 Nov 2010. DWF. Added WINDOW keyword to allow graphic to be displayed in a resizable graphics window. 8 Dec 2010. DWF Modifications to allow cgContour to be drop-in replacement for old Contour commands in indexed color mode. 24 Dec 2010. DWF. Previous changes introduced problems with OVERPLOT that have now been fixed. 28 Dec 2010. DWF. Set NOERASE keyword from !P.NoErase system variable when appropriate. 28 Dec 2010. DWF. Additional problems with NOERASE discovered and solved. 29 Dec 2010. DWF. Change to DECOMPOSED color was using incorrect color tables. 29 Dec 2010. DWF. In some cases, I was turning BYTE values to strings without converting to INTEGERS first. 30 Dec 2010. DWF. Still working on getting contour colors to work in decomposed color mode in all circumstances. 2 Jan 2011. DWF. Fixed problem with FILL when no contour colors (C_COLORS) are specified. 3 Jan 2011. DWF. Fixed a problem that preventing output keyword (e.g., PATH_INFO) from being returned properly. 3 Jan 2011. DWF. Fixed a problem calculating NLEVELS when LEVELS keyword was used instead. 3 Jan 2011. DWF. TVLCT commands protected from NULL device. 4 Jan 2011. DWF. Fixed a no color problem when CELL_FILL was set. 11 Jan 2011. DWF. Fixed a problem with overlaying filled contours with /OVERPLOT. 11 Jan 2011. DWF. Selecting character size now with cgDefCharSize. 11 Jan 2011. DWF. Moved setting to decomposed color before color selection process to avoid PostScript background problems when passed 24-bit color integers. 12 Jan 2011. DWF. Fixed a problem in which I assumed the background color was a string. 18 Jan 2011. DWF. Added ADDCMD keyword. 26 Jan 2011. DWF. Added LAYOUT keyword. 28 Jan 2011. DWF. Added PALETTE keyword. 4 Feb 2011. DWF. Color table vectors must be obtained AFTER loading the color palette. 6 March 2011. DWF. Modified error handler to restore the entry decomposition state if there is an error. 17 March 2011. DWF Modifications to allow palettes of less than 256 elememts in length to be used. 1 April 2011. DWF. Modifications to repair axes and tickmarks when creating filled contour plots. 28 May 2011. DWF. Whoops! Last fix shouldn't apply to OVERPLOTTING. Fixed. 22 June 2011. DWF. Still more work to get axes overplotting to work correct. 5 July 2011. DWF. Added an ONIMAGE keyword that allows the contours to be overplotted on top of an image that has been displayed with cgImage. This requires that the SAVE keyword is set in the cgImage call. Improved error handling. 26 Aug 2011. DWF. Got the data type correct in the part of the code that creates levels. 6 Sept 2011. DWF. Small change to allow cgWindow to set the current graphics window if it is the only window on the display. 15 Sept 2011. DWF. Had to add XTICKV, YTICKV, XTICKS, and YTICKS keywords to get repaired axes to work properly on filled contour plots. There may be other keywords needed, but I am going to add them on an as-needed basis. 30 Sept 2011. DWF. Other keywords WERE needed! I added XTICKLEN and YTICKLEN keywords to the repaired axes code. 3 Oct 2011. DWF. Change from 15 Sept 2011 forgot to include the possibility of pixmap windows. Algorithm made more robust. 27 Oct 2011. DWF. There was a problem with axes when plotting contours in 3D that has been fixed. 18 Nov 2011. DWF. Added OLEVELS keyword. 7 Dec 2011. DWF. Added OUTLINE and OUTCOLOR keywords. 8 Dec 2011. DWF. Modified the way the axes are drawn when given a negative tick length. 9 Dec 2011. DWF. Added the ability to send the output directly to a file via the OUTPUT keyword. 9 Dec 2011, DWF. PostScript, PDF, and Imagemagick parameters can now be tailored with cgWindow_SetDefs. 14 Dec 2001. DWF. Made sure the OUTLINE keyword works with CELL_FILL, too. 16 Dec 2011. DWF. Modified to use cgDefaultColor for default color selection. 24 Dec 2011. DWF. Added MAP_OBJECT keyword. 28 Dec 2011. DWF. Changes to allow better default colors, based on changes to cgColor and cgDefaultColor. 1 Feb 2012. DWF. Axis repair for filled contour plots (done with AXIS) results in incorrect tick labeling with date/time axes. Replaced repair code with actual Contour command. 9 March 2012. DWF. Fixed a problem with color palettes by defining NLEVELS according to the number of colors in the palette. 19 March 2012. DWF. Now allowing the user to draw in the "background" color, if the COLOR or AXISCOLOR is "BACKGROUND". 19 March 2012. DWF. The axis repair change on 9 March was not working in multi plots because the plot was already advanced. Added a fix to make sure the repair is to the correct multi plot. 20 April 2012. DWF. :Copyright: Copyright (c) 2010, Fanning Software Consulting, Inc.
(See $IDLUTILS_DIR/goddard/pro/coyote/cgcontour.pro)
CGCONTROL
Allows the user to set various properties of an cgWindow object. This is essentially a wrapper to the cgWindow SetProperty method. :Categories: Graphics :Params: selection: in, required, type=varies Normally, a window index number of an cgWindow application. But, the selection can be a widget identifier, an object reference, or a window title, depending on which keywords are set. The cgWindow matching the selection has its properties set. :Keywords: all: in, optional, type=boolean This keyword applies only to keywords that manipulate commands in the command list (e.g., DeleteCmd). It will select all the commands in the command list to apply the action to. adjustsize: in, optional, type=boolean Set this keyword to adjust default character size to the display window size. aspect: in, optional, type=boolean Set this keyword to the desired aspect ratio (ysize/xsize) of the window. background: in, optional, type=string The background color of the window. Only use if the ERASEIT property is also set. cmdindex: in, optional, type=integer This keyword applies only to keywords that manipulate commands in the command list (e.g., DeleteCmd). It specifies the command index number of the command for which the action is desired. create_bmp: in, optional, type='string', default='cgwindow.bmp' Set this keyword to the name of a bitmap file to create automatically from the window. Using this keyword is a way to create a bitmap file programmatically from a cgWindow application. The raster file will be created via ImageMagick if im_raster has been set (default). Depreciated now in favor of the `Output` keyword. create_gif: in, optional, type='string', default='cgwindow.gif' Set this keyword to the name of a GIF file to create automatically from the window. Using this keyword is a way to create a GIF file programmatically from a cgWindow application. The raster file will be created via ImageMagick if im_raster has been set (default). Depreciated now in favor of the `Output` keyword. create_jpeg: in, optional, type='string', default='cgwindow.jpeg' Set this keyword to the name of a JPEG file to create automatically from the window. Using this keyword is a way to create a JPEG file programmatically from a cgWindow application. The raster file will be created via ImageMagick if im_raster has been set (default). Depreciated now in favor of the `Output` keyword. create_pdf: in, optional, type='string', default='cgwindow.pdf' Set this keyword to the name of a PNG file to create automatically from the window. Using this keyword is a way to create a PDF file programmatically from a cgWindow application. The PDF file will be created via the Coyote Graphics program cgPS2PDF. Depreciated now in favor of the `Output` keyword. create_png: in, optional, type='string', default='cgwindow.png' Set this keyword to the name of a PNG file to create automatically from the window. Using this keyword is a way to create a PNG file programmatically from a cgWindow application. The raster file will be created via ImageMagick if im_raster has been set (default). create_ps: in, optional, type='string', default='cgwindow.ps' Set this keyword to the name of a PostScript file to create automatically from the window. Using this keyword is a way to create a PostScript file programmatically from a cgWindow application. Depreciated now in favor of the `Output` keyword. create_tiff: in, optional, type='string', default='cgwindow.tiff' Set this keyword to the name of a TIFF file to create automatically from the window. Using this keyword is a way to create a TIFF file programmatically from a cgWindow application. The raster file will be created via ImageMagick if im_raster has been set (default). Depreciated now in favor of the `Output` keyword. delay: in, optional, type=float Set this keyword to the amount of "delay" you want between commands in the command list. deletecmd: in, optional, type=boolean Set this keyword to delete a command in the cgWindow. The keywords cmdIndex and All are used in deleting the specified command. destroy: in, optional, type=boolean Set this keyword to destroy the cgWindow program. This keyword should not be used with other keywords. dimensions: in, optional, type=intarr(2) Set this keyword to a two-element array giving the xsize and ysize of the draw widget. eraseit: in, optional, type=boolean If this property is set, the cgWindow erases with the background color before displaying the commands in the window's command list. execute: in, optional, type=boolean Set this keyword to 1 to exectute the commands in the window's command list. Set this keyword to 0 to prevent command excution. This is useful, for example, if you want to load commands without having them be executed immediately. get_keycmdindex: in, optional, type=integer Set this value to the number of the command (zero-based) for which you want to obtain the keyword value. If not provided, the first command (command 0) is searched. get_keyword: in, optional, type=string The name of the keyword whose value you want to return in get_keyvalue. The name must be spelled EXACTLY as you used the keyword, except that case does not matter. The string is converted to UPPERCASE to locate the proper keyword. Although it was my intention to use this to retrieve output keyword values, this is not possible using cgWindow due to the way Call_Procedure and keyword inheritance work. get_keyvalue: out, optional, type=any The value of the keyword specified in get_keyword. If the keyword cannot be found, this value will be undefined. You MUST check for this before using the return variable in your program. im_transparent: in, optional, type=boolean, default=0 Set this keyword to allow ImageMagick to create transparent backgrounds when it makes raster image files from PostScript output. im_density: in, optional, type=integer, default=300 Set this keyword to the sampling density when ImageMagick creates raster image file from PostScript outout. im_options: in, optional, type=string, default="" Set this keyword to any ImageMagick options you would like to pass along to the ImageMagick convert command when creating raster image files from PostScript output. im_resize: in, optional, type=integer, default=25 Set this keyword to percentage that the raster image file created my ImageMagick from PostScript output should be resized. im_raster: in, optional, type=boolean, default=1 Set this keyword to zero to create raster files using the create_png etc. keywords directly, instead of via ImageMagick. im_width: in, optional, type=integer Set this keyword to the width of the output raster file in pixel units. The height of the raster file is set to preserve the aspect ratio of the output image. Applies only to raster images (eg PNG, JPEG, TIFF, etc.) created from PostScript files with ImageMagick. multi: in, optional, type=Intarr(5) Set this keyword to the !P.MULTI setting you want to use for the window. !P.MULTI is set to this setting before command execution, and set back to it's default value when the commands are finished executing. object: in, optional, type=boolean If this keyword is set, the selection is assumed to be an object reference. output: in, optional, type=string This keyword should be set to the name of an output file. It is a short-hand way of specifying the CREATE_*** keywords. The type of file is taken from the file name extension. palette: in, optional, type=byte Use this keyword to pass in an N-by-3 (or 3-by-N) byte array containing the R, G, and B vectors of a color table. It is probably easier to use cgLoadCT or XCOLORS to load color tables for the window, but this is provided as another option. pdf_path: out, optional, type=string Set this keyword to the name of the path to the Ghostscript command for converting PS to PDF. pdf_unix_convert_cmd: out, optional, type=string Set this keyword to the name of an alternative UNIX command to convert PostScript to PDF. ps_charsize: in, optional, type=float The PostScript character size. ps_decomposed: in, optional, type=boolean, default=0 Set this keyword to zero to set the PostScript color mode to indexed color and to one to set the PostScript color mode to decomposed color. ps_delete: in, optional, type=boolean, default=1 Set this keyword to zero if you want to keep the PostScript output ImageMagick creates when making raster file output. ps_encapsulated: in, optional, type=boolean, default=0 Set this keyword to configure PSCONFIG to produce encapsulated PostScript output by default. ps_font: in, optional, type=integer Set this keyword to the type of font you want to use in PostScript output. It sets the FONT keyword on the PSConfig command. Normally, 0 (hardware fonts) or 1 (true-type fonts). ps_metric: in, optional, type=boolean, default=0 Set this keyword to configure PSCONFIG to use metric values and A4 page size in its interface. ps_quiet: in, optional, type=boolean, default=0 Set this keyword to set the QUIET keyword on PS_Start. ps_scale_factor: in, optional, type=float Set his keyword to the PostScript scale factor you wish to use in creating PostScript output. ps_tt_font: in, optional, type=string Set this keyword to the name of a true-type font to use in creating PostScript output. restore_visualization: in, optional, type=string Set this keyword to the name of a visualization save file to restore. save_visualization: in, optional, type=string, default='graphic.cgs' Set this keyword to the name of a file where the visualization should be saved. title: in, optional, type=boolean If this keyword is set, the selection is assumed to be a window title. All matching is done in uppercase characters. update: in, optional, type=boolean, default=1 Set this keyword to zero if you do not want the updates to be done immediately after the properties are changed. widgetid: in, optional, type=boolean If this keyword is set, the selection is assumed to be a widget identifier. xomargin: in, optional, type=intarr(2) Sets the !X.OMargin system variable when multiple plots are displayed in the window. yomargin: in, optional, type=intarr(2) Sets the !Y.OMargin system variable when multiple plots are displayed in the window. :Examples: Used to set cgWindow properties:: IDL> cgControl, Background='gray', EraseIt=1 IDL> cgControl, Multi=[0,2,2] :Author: FANNING SOFTWARE CONSULTING:: David W. Fanning 1645 Sheely Drive Fort Collins, CO 80526 USA Phone: 970-221-0438 E-mail: david@idlcoyote.com Coyote's Guide to IDL Programming: http://www.idlcoyote.com/ :History: Change History:: Written, 28 January 2011. DWF. Added CREATE_PS keyword. 16 Feb 2011. DWF. Added PS_QUIET, GET_KEYCMDINDEX, GET_KEYWORD, and GET_KEYVALUE keywords. 17 Feb 2011. DWF. Added im_raster and the create_... raster options. 18 Feb 2011. Jeremy Bailin Added the ability to set and unset adjustable text size in cgWindow with ADJUSTSIZE keyword. 24 April 2011. DWF. Added the ability to set the dimensions of the draw widget programmatically. 14 June 2011. Added PS_DECOMPOSED keyword to set the PostScript color mode. 30 Aug 2011. DWF. Added SAVE_VISUALIZATION and RESTORE_VISUALIZATION keywords. 15 Sept 2011. DWF. Added ASPECT keyword to control window aspect ratio. 9 Nov 2011. DWF. Added CREATE_PDF, PDF_UNIX_CONVERT_CMD, and PDF_PATH keywords. 11 Dec 2011. DWF. Added IM_WIDTH keyword. 3 April 2012. DWF. Added the OUTPUT keyword. 3 April 2012. DWF. :Copyright: Copyright (c) 2011-2012, Fanning Software Consulting, Inc.
(See $IDLUTILS_DIR/goddard/pro/coyote/cgcontrol.pro)
CGDEFAULTCOLOR
The purpose of this function is to choose a default color for Coyote Graphics routines. :Categories: Graphics :Returns: Returns a scalar or vector (depends on the type of the input color) of color names (strings) to be used as the "color" in Coyote Graphics routines. If the MODE is 1 and the inputColor is of type LONG, then the return value is an array or scalar of type LONG. :Params: inputcolour: in, optional The input color. May be undefined, a byte, integer, long, or string. If the device is in indexed color mode at the time the request is made, then all, byte, integer, and long values will be treated as indices into the current color table. The variable may be a vector. :Keywords: background: in, optional, type=boolean If this keyword is set, the color is treated as a background color. Otherwise, it is treated as a drawing color. default: in, optional A color of any type allowed as the `inputColour`. Used if the `inputColour` is undefined. mode: in, optional, type=boolean The color mode. A 0 mean indexed color mode. A 1 means decomposed color mode. If not supplied in the call, the color mode is determined at run-time with `GetDecomposedState`. The color mode is *always* determined at run time if the current graphics device is the PostScript device. traditional: in, optional, type=boolean, default=0 Set this keyword if you are using the traditional color scheme of white foreground and black background. If this keyword is set, and the current graphics device is the PostScript device, the colors will be reversed, in the traditional IDL graphics way. :Examples: Use as a device independent way to get a color:: background = cgDefaultColor(bColor, /Background) color = cgDefaultColor(bColor) cgPlot, cgDemoData, Background=background, Color=color :Author: FANNING SOFTWARE CONSULTING:: David W. Fanning 1645 Sheely Drive Fort Collins, CO 80526 USA Phone: 970-221-0438 E-mail: david@idlcoyote.com Coyote's Guide to IDL Programming: http://www.idlcoyote.com :History: Change History:: Written, 24 December 2011. David W. Fanning. Modified to make sure a LONG integer in indexed color mode is in the range 0-255. 10 Jan 2012. DWF. Modified to make sure MODE is always determined at run-time for PostScript device. 14 Jan 2012. DWF. Allow other data types to be treated as color table index numbers, as long as they are in the range 0 to 255, and the MODE indicates indexed color. 7 March 2012. DWF. Modified so that the variable MODE will not change in the calling program program. 8 March 2012. DWF. :Copyright: Copyright (c) 2011, Fanning Software Consulting, Inc.
(See $IDLUTILS_DIR/goddard/pro/coyote/cgdefaultcolor.pro)
CGDEFCHARSIZE
Defines a default character size for Coyote Graphics routines (cgPlot, cgContour, etc.) IF !P.Charsize is set, the function simply returns !P.Charsize. :Categories: Graphics, Utilities :Keywords: adjustsize: in, optional, type=boolean, default=0 If this keyword is set, the output character size is adjusted to fit the size of the output graphics window. No adjustment is ever done in PostScript. Applies only when !P.Charsize=0. font: in, optional, type=integer, default=!P.Font The font type: -1 = Hershey, 0 = hardware, 1 = true-type. :Author: FANNING SOFTWARE CONSULTING:: David W. Fanning 1645 Sheely Drive Fort Collins, CO 80526 USA Phone: 970-221-0438 E-mail: david@idlcoyote.com Coyote's Guide to IDL Programming: http://www.idlcoyote.com :History: Change History:: Written, 11 January 2011. DWF. Added an ADJUSTSIZE keyword to allow adjustable sizing of characters in resizeable graphics windows. 24 April 2011. DWF. Made sure this program only adjusts text size on devices that support windows. 20 July 2011. DWF. :Copyright: Copyright (c) 2011, Fanning Software Consulting, Inc.
(See $IDLUTILS_DIR/goddard/pro/coyote/cgdefcharsize.pro)
CGDISPLAY
The purpose of cgDisplay is to open a graphics window on the display, or in the PostScript device, or in the Z-graphics buffer, depending upon the current graphics device. In PostScript a window of the proper aspect ratio is created with PSWindow. Using cgDisplay to open "windows" will allow you to more easily write device-independent IDL programs. :Categories: Graphics :Params: pxsize: in, optional, type=integer, default=640 The X size of the graphics window created. By default, 640. pysize: in, optional, type=integer, default=512 The Y size of the graphics window created. By default, 512. :Keywords: aspect, in, optional, type=float Set this keyword to create a window with this aspect ratio (ysize/xsize). If aspect is greater than 1, then the ysize will be used in the aspect ratio calculation. If the aspect is less than or equal to 1, then the xsize will be used in the aspect ratio calculation of the final window size. If the input to the ASPECT keyword is an image, then the aspect ratio will be calculated from the image itself. color: in, optional, type=string/integer, default='white' If this keyword is a string, the name of the data color. By default, 'white'. Color names are those used with cgColor. Otherwise, the keyword is assumed to be a color index into the current color table. The color is not used if the "window" is opened in PostScript on the Z-graphics buffer. force: in, optional, type=boolean, default=0 Because of the way cgDisplay is designed to work in many devices and in resizeable graphics windows, it is sometimes the case that it won't create a window for you. If you set this keyword, a graphics window will be created while in any device that supports graphics windows. free: in, optional, type=boolean, default=0 Set this keyword to open a window with a free or unused window index number. This keyword applied only to graphics windows created on the computer display. match: in, optional, type=boolean, default=0 If this keyword is set, the new display window will match the size of the current display window, if there is one. wid: in, optional, type=integer, default=0 The window index number of the IDL graphics window to create. window: in, optional, type=integer, default=0 Because I want to use cgDisplay everywhere, including in resizeable graphics windows, and I don't want it opening windows then, it first checks to be sure there are no resizeable graphics windows on the display before it creates a window. Setting this keyword will overrule this check and create a normal IDL graphics window on the display. This will allow you to open a normal graphics window at the same time a resizeable graphics window exists on the display. xsize: in, optional, type=integer, default=640 The X size of the graphics window created. By default, 640. The PXSIZE parameter is used in preference to the XSIZE keyword value. ysize: in, optional, type=integer, default=512 The Y size of the graphics window created. By default, 512. The PYSIZE parameter is used in preference to the YSIZE keyword value. _extra: in, optional, type=any Any keywords supported by the WINDOW command are allowed. :Examples: Use like the IDL WINDOW command:: IDL> cgDisplay, XSIZE=500 YSIZE=400 IDL> cgDisplay, 500, 500, WID=1, COLOR='gray' :Author: FANNING SOFTWARE CONSULTING:: David W. Fanning 1645 Sheely Drive Fort Collins, CO 80526 USA Phone: 970-221-0438 E-mail: david@idlcoyote.com Coyote's Guide to IDL Programming: http://www.idlcoyote.com :History: Change History:: Written, 15 November 2010. DWF. Changes so that color variables don't change type. 23 Nov 2010. DWF. Moved the window index argument to the WID keyword. 9 Dec 2010. DWF. Modified to produce a window in PostScript and the Z-buffer, too. 15 Dec 2010. DWF. Added the FREE keyword. 3 January 2011. DWF. I made a change that allows you to call cgDisplay inside a program that is going to be added to a cgWindow. The program will not open a graphics window if the current graphics window ID is found in a list of cgWindow window IDs. It is now possible to use cgDisplay in any graphics program, even those that will be run in cgWindow. 17 Nov 2011. DWF. Added ASPECT keyword. 18 Nov 2011. DWF. Allowed the window ASPECT to be set with an image argument. 25 Nov 2011. DWF. Now use Scope_Level to always create a display when cgDisplay is called from the main IDL level. 7 Feb 2012. DWF. Added FORCE and MATCH keywords. 16 Feb 2012. DWF. :Copyright: Copyright (c) 2010-2012, Fanning Software Consulting, Inc.
(See $IDLUTILS_DIR/goddard/pro/coyote/cgdisplay.pro)
CGERASE
Provides a device-independent and color-model-independent way to erase a graphics window with a particular color. :Categories: Graphics :Params: background_color: in, optional, type=string/integer/long, default='white' The color to use in erasing the graphics window. Default is "white." Color names are those used with cgColor. :Keywords: color: in, optional, type=string/integer/long, default='white' An alternative way to specify the color to use in erasing the graphics window. Color names are those used with cgColor. This parameter is used in preference to the background_color parameter. layout: in, optional, type=intarr(3) This keyword specifies a grid with a graphics window and determines where the graphic should appear. The syntax of LAYOUT is three numbers: [ncolumns, nrows, location]. The grid is determined by the number of columns (ncolumns) by the number of rows (nrows). The location of the graphic is determined by the third number. The grid numbering starts in the upper left (1) and goes sequentually by column and then by row. If this keyword is used, only this portion of the window is erased. window: in, optional, type=boolean, default=0 Set this keyword to erase the current cgWindow application. "Erasing" in this case means removing all the current commands. :Examples: Used to "erase" various things:: IDL> cgErase IDL> cgErase, 'gray' IDL> cgErase, COLOR='charcoal' IDL> cgPlot, cgDemoData(1), /Window IDL> cgErase, /Window IDL> cgPlot, cgDemoData(17), Layout=[2,2,1] IDL> cgPlot, cgDemoData(17), Layout=[2,2,4] IDL> cgErase, Layout=[2,2,1] :Author: FANNING SOFTWARE CONSULTING:: David W. Fanning 1645 Sheely Drive Fort Collins, CO 80526 USA Phone: 970-221-0438 E-mail: david@idlcoyote.com Coyote's Guide to IDL Programming: http://www.idlcoyote.com :History: Change History:: Written, 12 November 2010. DWF. Modified so that input variables are not changed. 18 Nov 2010. DWF. Got my color selection algorithm right. COLOR keyword takes precedence over the parameter. 18 Nov 2010. DWF. Modified to erase in decomposed color, if possible. In some cases, I was turning BYTE values to strings without converting to INTEGERS first. 30 Dec 2010. DWF. Added WINDOW keyword. 26 Jan 2011. DWF. Added LAYOUT keyword. 1 Feb 2011. DWF. Modified error handler to restore the entry decomposition state if there is an error. 17 March 2011. DWF :Copyright: Copyright (c) 2010, Fanning Software Consulting, Inc.
(See $IDLUTILS_DIR/goddard/pro/coyote/cgerase.pro)
CGPICKFILE
This is a utility program for selecting data files. It is a wrapper for DIALOG_PICKFILE, with the additional functionality of being able to "remember" the name and directory of the last file selected by the program. It basically allows you to start the next file selection from the location of the previous file selection. :Categories: Utility :Returns: The fully-qualified name of the selected file or a null string if the CANCEL button was selected. :Keywords: datadir: in, optional, type=string Set this keyword to the name of the data directory. If not set, the program assumes the data directory is rooted in the directory that holds this program file, or the directory directly above it. If it can't find a "data" directory in either of these two locations, the current directory is used as the "data" directory. The data directory is ONLY used if there is no "current" last directory. In other words, it is only used if cgPickfile has not been called in the current IDL session. demo: in, optional, type=boolean, default=0 If set, starts in the !DIR/examples/data directory. jpeg: in, optional, type=boolean, default=0 If set, starts in the "jpeg" directory. It assumes the jpeg directory is rooted in the "data" directory. hdf: in, optional, type=boolean, default=0 If set, starts in the "hdf" directory. It assumes the hdf directory is rooted in the "data" directory. last_file: in, optional, type=boolean, default=0 If set, the name of the last file opened is placed in the filename widget. lidar: in, optional, type=boolean, default=0 If set, starts in the "lidar" directory. It assumes the lidar directory is rooted in the "data" directory. ncdf: in, optional, type=boolean, default=0 If set, starts in the "ncdf" directory. It assumes the ncdf directory is rooted in the "data" directory. png: in, optional, type=boolean, default=0 If set, starts in the "png" directory. It assumes the png directory is rooted in the "data" directory. tiff: in, optional, type=boolean, default=0 If set, starts in the "tiff" directory. It assumes the tiff directory is rooted in the "data" directory. title: in, optional, type=string, default="Please Select a File" The title for the selection dialog window. If the `Write` keyword is set, the default title becomes "Please Select a File for Writing". write: in, optional, type=boolean, default=0 Set this keyword to change the default title to "Please Select a File for Writing". _ref_extra: in, optional Accepts any input keywords to DIALOG_PICKFILE (e.g., FILTER). :Author: FANNING SOFTWARE CONSULTING:: David W. Fanning 1645 Sheely Drive Fort Collins, CO 80526 USA Phone: 970-221-0438 E-mail: david@idlcoyote.com Coyote's Guide to IDL Programming: http://www.idlcoyote.com :History: Change History:: Adapted from FSC_PICKFILE to be a Coyote Graphics routine by David W. Fanning, 4 Aug 2011. Added keywords TITLE and WRITE to work around a bug in Dialog_Pickfile that clips the input filenames. 25 Feb 2012. DWF. :Copyright: Copyright (c) 2011, Fanning Software Consulting, Inc.
(See $IDLUTILS_DIR/goddard/pro/coyote/cgpickfile.pro)
CGPLOT
The purpose of cgPlot is to create a wrapper for the traditional IDL graphics command, Plot. The primary purpose of this is to create plot commands that work and look identically both on the display and in PostScript files. Program default colors will depend on the IDL graphics window. If no windows are currently open when the program is called, cgDisplay is used to create a window. The program requires the `Coyote Library <http://www.idlcoyote.com/documents/programs.php>` to be installed on your machine. :Categories: Graphics :Params: x: in, required, type=any If X is provided without Y, a vector representing the dependent values to be plotted If both X and Y are provided, X is the independent parameter and Y is the dependent parameter to be plotted. y: in, optional, type=any A vector representing the dependent values to be plotted. :Keywords: addcmd: in, optional, type=boolean, default=0 Set this keyword to add the command to the resizeable graphics window cgWindow. aspect: in, optional, type=float, default=none Set this keyword to a floating point ratio that represents the aspect ratio (ysize/xsize) of the resulting plot. The plot position may change as a result of setting this keyword. Note that `Aspect` cannot be used when plotting with !P.MULTI. axiscolor: in, optional, type=string/integer, default='opposite' If this keyword is a string, the name of the axis color. Otherwise, the keyword is assumed to be a color index into the current color table. axescolor: in, optional, type=string/integer Provisions for bad spellers. background: in, optional, type=string/integer, default='background' If this keyword is a string, the name of the background color. Otherwise, the keyword is assumed to be a color index into the current color table. charsize: in, optional, type=float, default=cgDefCharSize() The character size for axes annotations. Uses cgDefCharSize to select default character size, unless !P.Charsize is set, in which case !P.Charsize is always used. color: in, optional, type=string/integer, default='black' If this keyword is a string, the name of the data color. By default, 'black'. Color names are those used with cgColor. Otherwise, the keyword is assumed to be a color index into the current color table. font: in, optional, type=integer, default=!P.Font The type of font desired for axis annotation. isotropic: in, optional, type=boolean, default=0 A short-hand way of setting the `Aspect` keyword to 1. layout: in, optional, type=intarr(3) This keyword specifies a grid with a graphics window and determines where the graphic should appear. The syntax of LAYOUT is three numbers: [ncolumns, nrows, location]. The grid is determined by the number of columns (ncolumns) by the number of rows (nrows). The location of the graphic is determined by the third number. The grid numbering starts in the upper left (1) and goes sequentually by column and then by row. nodata: in, optional, type=boolean, default=0 Set this keyword to draw axes, but no data. noerase: in, optional, type=boolean, default=0 Set this keyword to draw the plot without erasing the display first. outfilename: in, optional, type=string If the `Output` keyword is set, the user will be asked to supply an output filename, unless this keyword is set to a non-null string. In that case, the value of this keyword will be used as the filename and there will be no dialog presented to the user. output: in, optional, type=string, default="" Set this keyword to the type of output desired. Possible values are these:: 'PS' - PostScript file 'EPS' - Encapsulated PostScript file 'PDF' - PDF file 'BMP' - BMP raster file 'GIF' - GIF raster file 'JPEG' - JPEG raster file 'PNG' - PNG raster file 'TIFF' - TIFF raster file Or, you can simply set this keyword to the name of the output file, and the type of file desired will be determined by the file extension. If you use this option, the user will not be prompted to supply the name of the output file. All raster file output is created through PostScript intermediate files (the PostScript files will be deleted), so ImageMagick and Ghostview MUST be installed to produce anything other than PostScript output. (See cgPS2PDF and PS_END for details.) And also note that you should NOT use this keyword when doing multiple plots. The keyword is to be used as a convenient way to get PostScript or raster output for a single graphics command. Output parameters can be set with cgWindow_SetDefs. overplot: in, optional, type=boolean, default=0 Set this keyword if you wish to overplot data on an already exisiting set of axes. It is like calling the IDL OPLOT command. position: in, optional, type=vector The usual four-element position vector for the Plot comamnd. Only monitored and possibly set if the `Aspect` keyword is used. psym: in, optional, type=integer Any normal IDL PSYM values, plus any value supported by the Coyote Library routine SYMCAT. An integer between 0 and 46. symcolor: in, optional, type=string/integer, default='black' If this keyword is a string, the name of the symbol color. By default, 'black'. Otherwise, the keyword is assumed to be a color index into the current color table. symsize: in, optional, type=float, default=1.0 The symbol size. traditional: in, optional, type=boolean, default=0 If this keyword is set, the traditional color scheme of a black background for graphics windows on the display is used and PostScript files always use a white background. window: in, optional, type=boolean, default=0 Set this keyword to replace all the commands in a current cgWindow or to create a new cgWindow for displaying this command. _ref_extra: in, optional, type=any Any keyword appropriate for the IDL Plot command is allowed in the program. :Examples: Use as you would use the IDL PLOT command:: cgPlot, Findgen(11) cgPlot, Findgen(11), Aspect=1.0 cgPlot, Findgen(11), Color='olive', AxisColor='red', Thick=2 cgPlot, Findgen(11), Color='blue', SymColor='red', PSym=-16 :Author: FANNING SOFTWARE CONSULTING:: David W. Fanning 1645 Sheely Drive Fort Collins, CO 80526 USA Phone: 970-221-0438 E-mail: david@idlcoyote.com Coyote's Guide to IDL Programming: http://www.idlcoyote.com :History: Change History:: Written, 12 November 2010. DWF. Added SYMCOLOR keyword, and allow all 46 symbols from SYMCAT. 15 November 2010. DWF. Added NODATA keyword. 15 November 2010. DWF. Now setting decomposition state by calling SetDecomposedState. 16 November 2010. DWF. Final color table restoration skipped in Z-graphics buffer. 17 November 2010. DWF. Fixed a problem with overplotting with symbols. 17 November 2010. DWF. Background keyword now applies in PostScript file as well. 17 November 2010. DWF. Many changes after BACKGROUND changes to get !P.MULTI working again! 18 November 2010. DWF. Fixed a small problem with the OVERPLOT keyword. 18 Nov 2010. DWF. Changes so that color inputs don't change type. 23 Nov 2010. DWF. Added WINDOW keyword to allow graphic to be displayed in a resizable graphics window. 8 Dec 2010. DWF Modifications to allow cgPlot to be drop-in replacement for old PLOT commands in indexed color mode. 24 Dec 2010. DWF. Previous changes introduced problems with OVERPLOT that have now been fixed. 28 Dec 2010. DWF. Set NOERASE keyword from !P.NoErase system variable when appropriate. 28 Dec 2010. DWF. Additional problems with NOERASE discovered and solved. 29 Dec 2010. DWF. In some cases, I was turning BYTE values to strings without converting to INTEGERS first. 30 Dec 2010. DWF. Selecting character size now with cgDefCharSize. 11 Jan 2011. DWF. Moved setting to decomposed color before color selection process to avoid PostScript background problems when passed 24-bit color integers. 12 Jan 2011. DWF. Changed _EXTRA to _REF_EXTRA on procedure definition statement to be able to return plot keywords such as XGET_TICKS. 13 Jan 2011. DWF. Added SYMSIZE keyword. 16 Jan 2011. DWF. Fixed a problem in which I assumed the background color was a string. 18 Jan 2011. DWF. Added ADDCMD keyword. 26 Jan 2011. DWF. Added LAYOUT keyword. 28 Jan 2011. DWF. Made a modification that allows THICK and COLOR keywords apply to symbols, too. 24 Feb 2011. DWF. Modified error handler to restore the entry decomposition state if there is an error. 17 March 2011. DWF Somehow I had gotten independent and dependent data reversed in the code. Put right. 16 May 2011. DWF. Allowed ASPECT (and /ISOTROPIC) to take into account input POSITION. 15 June 2011. Jeremy Bailin. Updated the BACKGROUND color selection from lessons learned in 27 Oct 2011 cgContour corrections. 27 Oct 2011. DWF. Added the ability to send the output directly to a file via the OUTPUT keyword. 9 Dec 2011, DWF. PostScript, PDF, and Imagemagick parameters can now be tailored with cgWindow_SetDefs. 14 Dec 2011. DWF. Modified to use cgDefaultColor for default color selection. 24 Dec 2011. DWF. Over-zealous use of _STRICT_EXTRA when overplotting resulted in errors. Now use _EXTRA. 1 Jan 2012. DWF. Changes to allow better default colors, based on changes to cgColor and cgDefaultColor. 1 Feb 2012. DWF. Now allowing the user to draw in the "background" color, if the COLOR or AXISCOLOR is "BACKGROUND". 19 March 2012. DWF. Scalar input parameters are changed to 1-element vectors to avoid annoying error messages from PLOT. 6 April 2012. DWF. :Copyright: Copyright (c) 2010-2012, Fanning Software Consulting, Inc.
(See $IDLUTILS_DIR/goddard/pro/coyote/cgplot.pro)
CGPLOTS
The purpose of cgPlotS is to create a wrapper for the traditional IDL graphics command, PlotS. The primary purpose of this is to create plot commands that work and look identically both on the display and in PostScript files. The program requires the `Coyote Library <http://www.idlcoyote.com/documents/programs.php>` to be installed on your machine. :Categories: Graphics :Params: X: in, required, type=any A vector or scalar argument providing the X components of the points to be drawn or connected. May be a 2xN or 3xN array, if Y and Z parameters are not used. Y: in, optional, type=any A vector or scalar argument providing the Y components of the points to be drawn or connected. Z: in, optional, type=any A vector or scalar argument providing the Z components of the points to be drawn or connected. :Keywords: addcmd: in, optional, type=boolean, default=0 Set this keyword to add the command to an cgWindow display. color: in, optional, type=string/integer, default='opposite' If this keyword is a string, the name of the data color. Color names are those used with cgColor. Otherwise, the keyword is assumed to be a color index into the current color table. May be a vector of the same length as X. map_object: in, optional, type=object If you are drawing on a map projection set up with Map_Proj_Init and using projected meter space, rather than lat/lon space, then you can use this keyword to provide a cgMap object that will allow you to convert the `x` and `y` parameters from longitude and latitude, respectively, to projected meter space before drawing. X and Y must both be present. psym: in, optional, type=integer Any normal IDL PSYM values, plus any value supported by the Coyote Library routine SYMCAT. An integer between 0 and 46. symcolor: in, optional, type=string/integer/vector, default=COLOR If this keyword is a string, the name of the symbol color. By default, same as COLOR. Otherwise, the keyword is assumed to be a color index into the current color table. May be a vector of the same length as X. symsize: in, optional, type=float/vector, default=1.0 A scalar or vector of symbol sizes. Default is 1.0. May be a vector of the same length as X. window: in, optional, type=boolean, default=0 Set this keyword to add the command to the current cgWindow application. _extra: in, optional, type=any Any keywords supported by the PLOTS command are allowed. :Examples: Use like the IDL PLOTS command:: IDL> cgPlot, Findgen(11) IDL> cgPlotS, !X.CRange, [5,5], LINESTYLE=2, THICK=2, COLOR='red' :Author: FANNING SOFTWARE CONSULTING:: David W. Fanning 1645 Sheely Drive Fort Collins, CO 80526 USA Phone: 970-221-0438 E-mail: david@idlcoyote.com Coyote's Guide to IDL Programming: http://www.idlcoyote.com :History: Change History:: Written, 12 November 2010. DWF. Added SYMCOLOR keyword. PSYM accepts all values from SYMCAT. SYMCOLOR and SYMSIZE keywords can be vectors the size of x. 15 November 2010. DWF Added ability to support COLOR keyword as a vector the size of x. 15 November 2010. DWF Now setting decomposition state by calling SetDecomposedState. 16 November 2010. DWF. Final color table restoration skipped in Z-graphics buffer. 17 November 2010. DWF. Changes so that color variables don't change type. 23 Nov 2010. DWF. Modified to use decomposed color, if possible. 24 Dec 2010. DWF. Whoops! Programming is like herding cats! 29 Dec 2010. DWF. In some cases, I was turning BYTE values to strings without converting to INTEGERS first. 30 Dec 2010. DWF. Moved setting to decomposed color before color selection process to avoid PostScript background problems when passed 24-bit color integers. 12 Jan 2011. DWF. Added WINDOW keyword. 24 Jan 2011. DWF. Made a modification that allows THICK and COLOR keywords apply to symbols, too. 24 Feb 2011. DWF. Modified error handler to restore the entry decomposition state if there is an error. 17 March 2011. DWF Fixed a problem in which the colors of the line was not accurate in some cases. 29 November 2011. DWF. Added the MAP_OBJECT keyword for plotting on map projections. 2 Jan 2012. DWF. :Copyright: Copyright (c) 2010-2012, Fanning Software Consulting, Inc.
(See $IDLUTILS_DIR/goddard/pro/coyote/cgplots.pro)
CGPS2PDF
Converts a PostScript file to a PDF file. This program requires the `Ghostscript <http://www.ghostscript.com/download/>` program to be installed on the user's computer, unless you are using a Macintosh computer or an alterntive UNIX command to do the conversion for you. If you are on a Macintosh, the supplied pstopdf program is used instead. Use the `UNIX_Convert_Cmd` keyword to select an alternative UNIX command (e.g., pstopdf or epstopdf). The program requires the `Coyote Library <http://www.idlcoyote.com/documents/programs.php>` to be installed on your machine. :Categories: Utilities, Graphics :Params: ps_file: in, required, type=string The name of the input PostScript file that is being converted to a PDF file. If not provided, the user will be asked to select a file. pdf_file: in, optional, type=string The name of the output PDF file. If not provided, the name is constructed from the input PostScript file name. :Keywords: delete_ps: in, optional, type=boolean, default=0 If this keyword is set, the PostScript file will be deleted after conversion. gs_path: in, optional, type=string This program assumes that UNIX users can access Ghostscript with the "gs" command. It assumes WINDOWS users have installed Ghostscript in either the C:\gs or C:\Program Files\gs directories. If either of these assumptions is incorrect, you can specify the directory where the Ghostscript executable resides with this keyword. (The Windows 32-bit executable is named gswin32c.exe and the 64-bit executable is named gswin64c.exe.) pagetype: in, optional, type=string, default="LETTER" Set this keyword to the "type" of page. Possible values are:: "Letter" - 8.5 by 11 inches. "Legal" - 8.5 by 14 inches. "Ledger" - 11 by 17 inches. "A4" - 21.0 by 29.7 centimeters. showcmd: in, optional, type=boolean, default=0 Set this keyword to print the command that is spawned in the command output window. silent: in, optional, type=boolean, default=0 Set this keyword to suppress output messages. success: out, optional, type=boolean Set this keyword to a named variable that on output will contain a 1 to indicate successful completion of the command, or to 0 otherwise. unix_convert_cmd: in, optional, type=string There are a number of commands on UNIX machines for converting PostScript files to PDF files. This program assumes you are using Ghostscript to do the conversion for you. The Ghostscript command on most UNIX machines is "gs", which is used if this keyword is undefined. However, if you would prefer to use another program to do the conversion for you, you can specify the name of the command here. For example, "pstopdf" or "epstopdf". In creating the actual command, this command will be separated by a space from the input file name. In other words, if the alternative conversion command was "pstopdf", the actual command would be "pstopdf" + " " + ps_file. Any output filename is ignored. This command does not apply to Macintosh or Windows computers. version: out, optional, type=string On exit, contains the version of Ghostscipt that was used. Not available on Macs or if an alternative UNIX command was used. :Examples: A typical sequence of commands to create a test.pdf file:: PS_Start, Filename='test.ps' cgHistoplot, cgDemoData(7), /Fill PS_End cgPS2PDF, 'test.ps' :Author: FANNING SOFTWARE CONSULTING:: David W. Fanning 1645 Sheely Drive Fort Collins, CO 80526 USA Phone: 970-221-0438 E-mail: david@idlcoyote.com Coyote's Guide to IDL Programming: http://www.idlcoyote.com :History: Change History:: Written, 6 December 2011, from code supplied to me by Paul Krummel. DWF. :Copyright: Copyright (c) 2011, Fanning Software Consulting, Inc.
(See $IDLUTILS_DIR/goddard/pro/coyote/cgps2pdf.pro)
CGQUERY
Provides information about any cgWindow applications currently on the display. Returns the window index numbers of any cgWindow applications current on the display. :Categories: Graphics :Keywords: count: out, optional, type=long The number of cgWindow applications currently on the display. current: in, optional, type=boolean If set, the current cgWindow application information is returned in the result of the function and in the information keywords. dimensions: out, optional, type=integer The dimensions of the ctWindow application, [xdim, ydim, n]. objectref: out, optional, type=object A vector of FSC_CMDWINDOW object references for each cgWindow application currently on the display. title: out, optional, type=string A vector of window titles for each cgWindow application currently on the display. widgetID: out, optional, type=long A vector of widget identifiers of the top-level base widget for each cgWindow application currently on the display. :Returns: windowIndexID: out, type=long An array of window index numbers for each cgWindow application currently on the display. :Examples: Used as a query routine:: IDL> wids = cgQuery(TITLE=titles, COUNT=count) IDL> index = Where(StrUpCase(titles) EQ 'PLOT WINDOW', tcnt) IDL> IF tcnt GT 0 THEN cgSet, wids[index] IDL> cgWindow, 'Oplot', thisData, /AddCmd :Author: FANNING SOFTWARE CONSULTING:: David W. Fanning 1645 Sheely Drive Fort Collins, CO 80526 USA Phone: 970-221-0438 E-mail: david@idlcoyote.com Coyote's Guide to IDL Programming: http://www.idlcoyote.com :History: Change History:: Written, 23 January 2011. DWF. Added DIMENSIONS keyword to return current dimensions of cgWindows. 24 Feb 2011. DWF. Made sure this program only returns information on devices that support windows. 20 July 2011. DWF. :Copyright: Copyright (c) 2011, Fanning Software Consulting, Inc.
(See $IDLUTILS_DIR/goddard/pro/coyote/cgquery.pro)
CGSET
Allows the user to select the cgWindow application to be the "current" application. Selection can be made based on window index number, widget identifier, object reference, or window title. :Categories: Graphics :Params: selection: in, optional, type=varies Normally, a window index number of an cgWindow application. But, the selection can be a widget identifier, an object reference, or a window title, depending on which keywords are set. The cgWindow matching the selection is made the "current" cgWindow and the application is moved forward on the display. :Keywords: display: in, optional, type=boolean, default=0 If this keyword is set, the selection is made the "current" application, and then the graphics window of the application is made the current graphics window. If there is no selection, then the current cgWindow graphics window is made the current graphics window. object: in, optional, type=boolean If this keyword is set, the selection is assumed to be an object reference. title: in, optional, type=boolean If this keyword is set, the selection is assumed to be a window title. All matching is done in uppercase characters. widgetid: in, optional, type=boolean If this keyword is set, the selection is assumed to be a widget identifier. :Examples: Used with query routine:: IDL> wids = cgQuery(TITLE=titles, COUNT=count) IDL> index = Where(StrUpCase(titles) EQ 'PLOT WINDOW', tcnt) IDL> IF tcnt GT 0 THEN cgSet, wids[index] IDL> cgWindow, 'Oplot', thisData, /AddCmd IDL> cgSet ; Bring current window forwad on display :Author: FANNING SOFTWARE CONSULTING:: David W. Fanning 1645 Sheely Drive Fort Collins, CO 80526 USA Phone: 970-221-0438 E-mail: david@idlcoyote.com Coyote's Guide to IDL Programming: http://www.idlcoyote.com :History: Change History:: Written, 23 January 2011. DWF. If selection match isn't provided, as like WShow to bring the current window forward on display. 26 Jan 2011. DWF. :Copyright: Copyright (c) 2011, Fanning Software Consulting, Inc.
(See $IDLUTILS_DIR/goddard/pro/coyote/cgset.pro)
CGSHOW
Allows the user to select the cgWindow application to be the brought forward on the display. Selection can be made based on window index number, widget identifier, object reference, or window title. This is the equivalent of WShow for normal graphics windows. :Categories: Graphics :Params: selection: in, required, type=varies Normally, a window index number of an cgWindow application. But, the selection can be a widget identifier, an object reference, or a window title, depending on which keywords are set. The cgWindow matching the selection is made the "current" cgWindow and the application is moved forward on the display. :Keywords: object: in, optional, type=boolean If this keyword is set, the selection is assumed to be an object reference. title: in, optional, type=boolean If this keyword is set, the selection is assumed to be a window title. All matching is done in uppercase characters. widgetid: in, optional, type=boolean If this keyword is set, the selection is assumed to be a widget identifier. :Examples: Used with query routine:: IDL> wids = cgQuery(TITLE=titles, COUNT=count) IDL> index = Where(StrUpCase(titles) EQ 'PLOT WINDOW', tcnt) IDL> IF tcnt GT 0 THEN cgSet, wids[index] IDL> cgWindow, 'Oplot', thisData, /AddCmd IDL> cgShow ; Bring current window forwad on display :Author: FANNING SOFTWARE CONSULTING:: David W. Fanning 1645 Sheely Drive Fort Collins, CO 80526 USA Phone: 970-221-0438 E-mail: david@idlcoyote.com Coyote's Guide to IDL Programming: http://www.idlcoyote.com :History: Change History:: Written, 1 February 2011. DWF. :Copyright: Copyright (c) 2011, Fanning Software Consulting, Inc.
(See $IDLUTILS_DIR/goddard/pro/coyote/cgshow.pro)
CGSNAPSHOT
To get accurate screen dumps with the IDL command TVRD on 24-bit PC and Macintosh computers, you have to be sure to set color decomposition on. This program adds that capability automatically. In addition, the program will optionally write BMP, GIF, JPEG, PICT, PNG, and TIFF color image files of the screen dump. :Categories: Graphics :Returns: The returned image will be a 2D image on 8-bit systems and a 24-bit pixel interleaved true-color image on 24-bit systems. A -1 will be returned if a file output keyword is used (e.g., JPEG, TIFF, etc.). :Params: xstart: in, optional, type=integer, default=0 The starting column index of the rectantular area that is to be copied. ystart: in, optional, type=integer, default=0 The starting row index of the rectantular area that is to be copied. ncols: in, optional, type=integer The number of columns to read in the rectantular area that is to be copied. By default, !D.X_Size - xstart. nrows: in, optional, type=integer The number of rows to read in the rectantular area that is to be copied. By default, !D.Y_Size - ystart. :Keywords: bmp: in, optional, type=boolean, default=0 Set this keyword to write the screen dump as a color BMP file. cancel: out, optional, type=boolean, default=0 An output keyword set to 1 if the user cancels out of a filename dialog. Set to 0 otherwise. colors: in, optional, type=integer, default=256 If a 24-bit image has to be quantized, this will set the number of colors in the output image. Applies to BMP, GIF, PICT, and PNG formats written from 24-bit displays.(See the COLOR_QUAN documentation for details.) cube: in, optional, type=integer If this keyword is set to a value between 2 and 6 the color quantization will use a cubic method of quantization. Applies to BMP, GIF, PICT, and PNG formats written from 24-bit displays.(See the COLOR_QUAN documentation for details.) dither: in, optional, type=boolean, default=0 If this keyword is set the quantized image will be dithered. Applies to BMP, GIF, PICT, and PNG formats written from 24-bit displays.(See the COLOR_QUAN documentation for details.) filename: in, optional, type=string The name of the output file. If you specify a name with a file extension of the type of file you want to create (e.g., *.jpg, *.png, etc), then you do not have to use the file type keywords (e.g., JPEG, PNG, etc.). Otherwise, you can specify the name of the the file without an extension, use the file keywords, and a file extension will be added to the filename automatically, depending upon the type of output file selected. gif: in, optional, type=boolean, default=0 Set this keyword to write the screen dump as a color GIF file. jpeg: in, optional, type=boolean, default=0 Set this keyword to write the screen dump as a color JPEG file. nodialog: in, optional, type=boolean, default=0 Set this keyword if you wish to avoid the DIALOG_PICKFILE dialog that asks you to name the output file. This keyword should be set, for example, if you are processing screens in batch mode. order: in, optional, type=boolean, default=0 Set this keyword to determine the image order for reading the display. Corresponds to !Order and set to such as the default. overwrite_prompt: in, optional, type=boolean, default=0 Set this keyword if you would like to get a prompt if you are overwriting a file. This applies only to operations involving DIALOG_PICKFILE. pict: in, optional, type=boolean, default=0 Set this keyword to write the screen dump as a color PICT file. png: in, optional, type=boolean, default=0 Set this keyword to write the screen dump as a color PNG file. tiff: in, optional, type=boolean, default=0 Set this keyword to write the screen dump as a color TIFF file. true: in, optional, type=integer, default=1 Set this keyword to the type of interleaving you want. 1 = Pixel interleaved, 2 = row interleaved, 3 = band interleaved. type: in, optional, type=string Set this keyword to the type of file to write. Use this instead of setting BMP, GIF, JPEG, PICT, PNG, or TIFF keywords: TYPE='JPEG'. The primary purpose of this is to make widget event handlers easier to write. quality: in, optional, type=integer, default=75 This keyword sets the amount of compression for JPEG images. It should be set to a value between 0 and 100. (See the WRITE_JPEG documentation for details.) wid: in, optional, type=integer The index number of the window to read from. The current graphics window (!D.Window) is selected by default. An error is issued if no windows are currently open on a device that supports windows. _ref_extra: in, optional Any keywords that are appropriate for the WRITE_*** routines are also accepted via keyword inheritance. :Examples: To obtain an image of the current graphics window:: IDL> image = cgSnapshot() To create a PNG file, named "test.png", of the current graphics window:: IDL> void = cgSnapshot(FILENAME='test.png') To obtain the lower quadrant of a 512-by-512 graphics window as a band interleaved image:: IDL> image = cgSnapshot(0, 0, 256, 256, TRUE=3) :Author: FANNING SOFTWARE CONSULTING:: David W. Fanning 1645 Sheely Drive Fort Collins, CO 80526 USA Phone: 970-221-0438 E-mail: david@idlcoyote.com Coyote's Guide to IDL Programming: http://www.idlcoyote.com :History: Change History:: Renamed TVRead to cgSnapshot and retired TVRead. 20 February 2011. DWF. Added the ability to get the file type from the file name extension. 26 Dec 2011. DWF. :Copyright: Copyright (c) 2011, Fanning Software Consulting, Inc.
(See $IDLUTILS_DIR/goddard/pro/coyote/cgsnapshot.pro)
CGTEXT
Provides a device-independent and color-model-independent way to write text into a graphics window. It is a wrapper to the XYOUTS command. :Categories: Graphics :Params: xloc: in, required, type=depends The X location of the text. yloc: in, required, type=depends The Y location of the text. text: in, optional, type=string The text to output. By default, the calling sequence of the program. :Keywords: addcmd: in, optional, type=boolean, default=0 Set this keyword to add the command to an cgWindow. Setting this keyword automatically sets the WINDOW keyword, but the command does not erase the graphics window as it would normally. alignment: in, optional, type=integer, default=0 Set this keyword to indicate the alignment of the text with respect to the x and y location. 0 is left aligned, 0.5 is centered, and 1.0 is right aligned. The alignment is set to 0.5 if PLACE is set and ALIGNMENT is unspecified. Otherwise, the default is 0. charsize: in, optional, type=float, default=cgDefCharSize() The character size for axes annotations. Uses cgDefCharSize to select default character size, unless !P.Charsize is set, in which case !P.Charsize is always used. color: in, optional, type=string/integer/long, default="opposite" The color of the text. Color names are those used with cgColor. data: in, optional, type=boolean Set this keyword to indicate xloc and yloc are in data coordinates. Data coordinates are the default, unless DEVICE or NORMAL is set. device: in, optional, type=boolean Set this keyword to indicate xloc and yloc are in device coordinates. font: in, optional, type=integer, default=!P.Font The type of font desired. By default, !P.Font. normal: in, optional, type=boolean Set this keyword to indicate xloc and yloc are in normalized coordinates. outloc: out, optional, type=various Only used if PLACE is set, this is a two-element array containing the xloc and yloc of the cursor position in the window. place: in, optional, type=boolean Set this keyword if you wish to click the cursor in the graphics window to place the text. If this keyword is set, you do not need to specify the `xloc` and `yloc` positional parameters. The first positional parameter is assumed to be the text. The clicked location will be returned in the `OutLoc` variable. If the `Alignment` keyword is not set, it will be set to 0.5 to set "center" as the default placement alignment. This has been modified to allow this keyword to work in a resizeable graphics window as well. Clicking once in the window will set the parameters so you don't have to click every time the window is resized. tt_font: in, optional, type=string The true-type font to use for the text. Only used if FONT=1. width: out, optional, type=float Set this keyword to a named variable in which to return the width of the text string, in normalized coordinate units. window: in, optional, type=boolean Set this keyword to add the command to the in the current cgWindow application. _ref_extra: in, optional Any keywords appropriate for the XYOUTS command. :Examples: Used like the IDL XYOUTS command:: IDL> cgText, 0.5, 0.5, 'This is sample text', ALIGNMENT=0.5, /NORMAL IDL> cgText, /PLACE, 'Use the cursor to locate this text', COLOR='dodger blue' :Author: FANNING SOFTWARE CONSULTING:: David W. Fanning 1645 Sheely Drive Fort Collins, CO 80526 USA Phone: 970-221-0438 E-mail: david@idlcoyote.com Coyote's Guide to IDL Programming: http://www.idlcoyote.com :History: Change History:: Written, 19 November 2010. DWF. Corrected a problem with setting text color and added PLACE and OUTLOC keywords. 25 Nov 2010. DWF. Humm, that text color problem got reset to the old way! Sheesh! Fixed. 9 Dec 2010. DWF. Modified the way the default color is selected. Drawing with DECOMPOSED if possible. 30 Dec 2010. DWF. Keywords collected with _REF_EXTRA so WIDTH can be returned. Added WIDTH keyword. 6 Jan 2011. DWF. Moved setting to decomposed color before color selection process to avoid PostScript background problems when passed 24-bit color integers. 12 Jan 2011. DWF. Added Window keyword. 24 Jan 2011. DWF. Added ability to return WIDTH from resizeable graphics windows and added ADDCMD keyword. 24 Feb 2011. DWF. Modified error handler to restore the entry decomposition state if there is an error. 17 March 2011. DWF Modified to allow the user to place the text in a resizeable graphics window. 13 Dec 2011. DWF. Modified to use cgDefaultColor for default color selection. 24 Dec 2011. DWF. Modifications to the way I obtain the WIDTH when adding the command to a cgWindow. 26 Jan 2012. DWF. :Copyright: Copyright (c) 2010, Fanning Software Consulting, Inc.
(See $IDLUTILS_DIR/goddard/pro/coyote/cgtext.pro)
CGWINDOW[1]
Creates a resizeable graphics window for IDL traditional commands (Plot, Contour, Surface, etc. or for Coyote Graphics routines, `cgPlot`, `cgContour`, `cgSurf`, etc.). In addition, the window contents can be saved as PostScript, PDF, or raster image files. If ImageMagick is installed on your machine, the raster image files can be created in very high quality from PostScript files. The program is designed to work with any IDL traditional graphics routine that is a procedure and includes no more than three positional parameters. Any number of keywords can be used to specify properties of the graphical output. Any number of graphics commands can be "added" the the cgWindow. Simply use the `AddCmd` keyword to add commands. If your program does not load its own color tables, the color tables in effect when cgWindow is first called are used to display the graphics commands. To create PostScript output from within cgWindow, your graphics program has to be written in such a way that it can work properly in the PostScript device. This means there are no Window commands, WSet commands, and the like that are not allowed in the PostScript device. Such commands are allowed in programs, of course, if they are "protected". Usually such protection looks like this:: IF (!D.Flags AND 256) NE 0 THEN Window, ... The Coyote Graphics program `cgDisplay` is a good program for opening graphics "windows", because such PostScript protection is built into the program. In a PostScript device, cgDisplay produces a "window" with the same aspect ratio as the current display graphics window, which is an aid in producing PostScript output that looks like the same output in the display window. Much better looking raster files can be created from the cgWindow contents, if the raster files are created by converting PostScript files to the raster file. If the ImageMagick "convert" command can be found on your machine, you will have the option to create raster files using this method. I *highly* recommend doing so, as fonts and other plot annotation will be of much higher quality using this method. cgWindow has been designed to work with other Coyote Graphics routines: `cgPlot`, `cgContour`, `cgSurf`, and so on, although I expect it to work with any IDL traditional graphics routine, if the routine is well written. :Categories: Graphics :Author: FANNING SOFTWARE CONSULTING:: David W. Fanning 1645 Sheely Drive Fort Collins, CO 80526 USA Phone: 970-221-0438 E-mail: david@idlcoyote.com Coyote's Guide to IDL Programming: http://www.idlcoyote.com :Copyright: Copyright (c) 2011, Fanning Software Consulting, Inc.
(See $IDLUTILS_DIR/goddard/pro/coyote/cgwindow.pro)
CGWINDOW[2]
Creates a resizeable graphics window for IDL traditional commands (Plot, Contour, Surface, etc. or for Coyote Graphics routines, cgPlot, cgContour, cgSurf, etc.). In addition, the window contents can be saved as PostScript files or as raster image files. If ImageMagick is installed on your machine, the raster image files can be created in very high quality from PostScript files. :Params: command: in, required, type=string The graphics procedure command to be executed. This parameter must be a string and the the command must be a procedure. Examples are 'Surface', 'Contour', 'Plot', 'cgPlot', cgContour, etc. p1: in, optional, type=any The first positional parameter appropriate for the graphics command. p2: in, optional, type=any The second positional parameter appropriate for the graphics command. p3: in, optional, type=any The third positional parameter appropriate for the graphics command. p4: in, optional, type=any The fourth positional parameter appropriate for the graphics command. :Keywords: addcmd: in, optional, type=boolean, default=0 Set this keyword to add an additional graphics command to an cgWindow. The command is added to the last created cgWindow, unless the WinID keyword is used to select another cgWindow. Adding a command causes all the commands in the window to be immediately executed. If this is not behavior you desire, use the LOADCMD keyword instead. If CMDINDEX is used to select a command index, the new command is added before the command currently occuping that index in the command list. altps_Keywords: in, optional, type=string A structure containing alternative keyword names (as tags) and values for those keywords to be used when the current device is the PostScript device. See http://www.idlcoyote.com/cg_tips/kwexpressions.php and the examples below for details on how to use this keyword. altps_Params: in, optional, type=IntArr(3) A structure containing alternative parameter values to be used when the current device is the PostScript device. Structure names are restricted to the names "P1", "P2", "P3" and "P4" to correspond to the equivalent positional parameter. See http://www.idlcoyote.com/cg_tips/kwexpressions.php and the examples below for details on how to use this keyword. cmddelay: in, optional, type=float If this keyword is set to a value other than zero, there will be a delay of this many seconds between command execution. This will permit "movies" of command sequences to be displayed. cmdindex: in, optional, type=integer This keyword is used to select which command in an cgWindow to act on when the AllCmd, DeleteCmd, LoadCmd and ReplaceCmd keywords are used. See the descriptions of these keywords for details on what happens when CmdIndex is missing. deletecmd: in, optional, type=boolean, default=0 Set this keyword to delete a graphics command from an cgWindow. If CmdIndex is undefined the last command entered into the window is deleted. It is not possible to delete the last command in the window. Use WinID to identify the cgWindow you are interested in. If WinID is undefined, the last cgWindow created is used. executecmd: in, optional, type=boolean, default=0 Set this keyword to immediate execute all the commands in an cgWindow. Normally, this is used after commands have been loaded with LOADCMD. group_leader: in, optional The identifier of a widget to serve as a group leader for this program. If the group leader is destroyed, this program is also destroyed. Used when calling this program from another widget program. listcmd: in, optional, type=boolean, default=0 If this keyword is set, the commands currently in the cgWindow are listed. Use WinID to identify the cgWindow you are interested in. If WinID is undefined, the last cgWindow created is used. loadcmd: in, optional, type=boolean, default=0 Set this keyword to add an additional graphics command to an cgWindow. The command is added to the last created cgWindow, unless the WinID keyword is used to select another cgWindow. Loaded commands are not automatically executed. Set the EXECUTECMD keyword at the end of loading to execute the loaded commands. If CMDINDEX is used to select a command index, the new command is loaded before the command currently occuping that index in the command list. method: in, optional, type=boolean, default=0 Set this keyword if the command is an object method call rather than a procedure call. If this keyword is set, the first positional parameter, p1, must be present and must be a valid object reference. replacecmd: in, optional, type=boolean, default=0 Set this keyword to replace a graphics command from an cgWindow. If CmdIndex is undefined, *all* commands in the window are replaced. Use WinID to identify the cgWindow you are interested in. If WinID is undefined, the last cgWindow created is used for the replacement. waspect: in, optional, type=float, default=normal Set this keyword to the aspect ratio you would like the window to have. The aspect ratio is calculated as (ysize/xsize). Must be a float value. If this keyword is set, the window will maintain this aspect ratio, even when it is resized. wbackground: in, optional, type=varies, default=!P.Background The background color of the window. Specifying a background color automatically sets the WErase keyword. werase: in, optional, type=boolean, default=0 Set this keyword to cause the window to be erased before graphics commands are drawn. This may need to be set, for example, to display images. winid: in, optional, type=integer Use this keyword to select the window cgWindow identifier (the number between the parentheses in the title bar of cgWindow). The AddCmd, ReplaceCmd, ListCmd, and DeleteCmd keywords will all apply to the commands in the last cgWindow created unless this keyword is used to select another cgWindow to apply the commands to. wmulti: in, optional, type=intarr(5) Set this keyword in exactly the same way you would set the !P.Multi keyword. It will allow you to display multi-plots in the cgWindow graphics window. wobject: out, optional, type=object cgWindow creates a FSC_CmdWindow object. This object reference is returned if this keyword is present. woxmargin: in, optional, type=float A two-element array indicating the left and right X outside margins for the graphical display. Used only when doing multiple plots with `WMulti`. woymargin: in, optional, type=float A two-element array indicating the bottom and top Y outside margins for the graphical display. Used only when doing multiple plots with `WMulti`. wxpos: in, optional, type=integer, default=5 The x offset in device coordinates of the cgWindow from the upper-left corner of the display. wypos: in, optional, type=integer, default=5 The y offset in device coordinates of the cgWindow from the upper-left corner of the display. wxsize: in, optional, type=integer, default=640 The x size in device coordinates of the graphics window. wysize: in, optional, type=integer, default=5 The y size in device coordinates of the the graphics window. wtitle: in, optional, type=string, default='Resizeable Graphics Window' The title of the graphics window. A window index number is appended to the title so multiple cgWindow programs can be selected. :Examples: Test code:: data = cgDemoData(17) cgWindow, 'cgPlot', data, COLOR='red' cgWindow, 'cgPlot', data, PSYM=2, /Overplot, COLOR='dodger blue', /AddCmd cgWIndow, 'cgPlot', cgDemoData(17), color='olive', linestyle = 2, /Overplot, /AddCmd cgWindow, /ListCmd cgWindow, 'cgPlot', data, COLOR='purple', /ReplaceCMD, CMDINDEX=0 Additional examples can be found here:: http://www.idlcoyote.com/graphics_tips/cgwindow.html Example using different keyword parameters for the display and PostScript output:: IDL> cgPlot, cgDemoData(1), /WINDOW, $ THICK=1.0, XTITLE='Distance (' + Greek('mu') + 'm)', $ ALTPS_KEYWORDS={THICK:4.0, XTITLE:'Distance (' + Greek('mu', /PS) + 'm)'} Example using different positional parameters:: IDL> cgText, 0.20, 0.85, /Normal, 'Line of Text', ALIGNMENT=0.0, $ ALTPS_KEYWORDS={ALIGNMENT:1.0}, ALTPS_PARAMS={P1:0.88}, /ADDCMD Additional examples can be found here:: http://www.idlcoyote.com/cg_tips/kwexpressions.php :History: Change History:: Written, 17 January 2011. DWF. Fixed a problem with the example code, and added EMPTY to end of Draw method to force UNIX machines to empty the graphics buffer after CALL_PROCEDURE. 20 Jan 2011. DWF. Improved documentation and error handling. 19 Jan 2011. DWF. More improved error handling and messages. 26 Jan 2011. DWF. Made changes to accommodate the new cgControl routine. 27 Jan 2011. DWF. Added WXOMARGIN and WYOMARGIN keywords. 28 Jan 2011. DWF. Numerous changes leading up to official release. 4 Feb 2011. DWF. Added workaround for UNIX bug for draw widget creation. 5 Feb 2011. DWF. Corrected a window aspect ratio problem with PostScript output by making the window the current window before calling PS_Start. 17 Feb 2011. DWF. Added machinery for programmatically generating raster files. 18 Feb 2011. Jeremy Bailin. Problem with restoring visualizations fixed. 6 March 2011. DWF. Fixed a problem with CALL_METHOD, which requires one positional parameter. 8 March 2011. DWF. Added the ability to set and unset adjustable text size in the window. 24 April 2011. DWF. Fixed a problem in the ReplaceCommand method that had input parameters reversed. 6 May 2011. DWF. Added the ability to set the dimensions of the draw widget programmatically. 14 June 2011. Added the keywords EvalKeywords and EvalParams to allow evaluation of command parameters and keywords at run-time. See http://www.idlcoyote.com/cg_tips/kwexpressions.php for additional details and explanations of how these keywords should be used. 2 Aug 2011. Problem dereferencing a null pointer in DRAW method fixed. 3 Aug 2011. DWF. Changes to handle inability to create raster files from PS encapsulated files in landscape mode. 26 Aug 2011. DWF. Added ability to set PostScript color mode. 30 Aug 2011. DWF. The method I was using for evaluating keyword and argument parameters at run-time was just WAY too complicated and difficult to use. I have eliminated this method (along with the EvalKeywords and EvalParams) in favor of a method that allows the user to supply alternative values to use in the PostScript device. This uses keywords AltPS_Keywords and AltPS_Params to collect these alternative arguments in structures that can be used at run-time to supply alternative values. As before, this is explained in detail at http://www.idlcoyote.com/cg_tips/kwexpressions.php. 1 Sept 2011. DWF. Missed a couple of places to set decomposition color mode. 7 Sept 2011. DWF. Fixed a problem with improper filename when creating raster file vis Imagemagick via cgControl. 10 Oct 2011. DWF. Added WASPECT keyword to allow window aspect ratio to be set. 9 Nov 2011. DWF. Added PDF file to the Save As menu. Requires Ghostscript to be installed on some machines. 6 Dec 2011. DWF. Added modifications to allow PDF files to be programmatically created from cgControl. 11 Dec 2011. DWF. Added the ability to specify a fourth positional parameter. 6 Jan 2012. DWF. Separated off the cgCmdWindow part of the code to make an object-widget draw widget. 19 Jan 2012. DWF. Fixed a small type with the Outside Margin keywords that was preventing these from being used. 19 April 2012. DWF.
(See $IDLUTILS_DIR/goddard/pro/coyote/cgwindow.pro)
CGWINDOW_GETDEFS
Allows the user to get the global defaults for resizeable cgWindow programs. :Categories: Graphics :Keywords: adjustsize: out, optional, type=boolean If set, adjust the default text size to match the display window size. aspect: out, optional, type=float The aspect ratio of the window. background: out, optional, type=string The background color of the window. delay: out, optional, type=float The amount of delay between command execution. eraseit: out, optional, type=boolean The Erase status of the window. im_density: out, optional, type=integer The sampling density. im_png8: out, optional, type=boolean If set, ImageMagick will create 8-bit PNG files, rather than 24-bit. im_options: out, optional, type=string Current ImageMagick convert options. im_raster: out, optional, type=boolean The raster via ImageMagick setting. im_resize: out, optional, type=integer The amount PostScript output is resized. im_transparent: out, optional, type=boolean The transparent background setting. im_width: out, optional, type=integer The final width of ImageMagick raster file output. multi: out, optional, type=Intarr(5) The !P.MULTI setting for the window. palette: out, optional, type=byte The window color palette. pdf_path: out, optional, type=string The name of the path to the Ghostscript command for converting PS to PDF. pdf_unix_convert_cmd: out, optional, type=string The name of an alternative UNIX command to convert PostScript to PDF. ps_charsize: out, optional, type=float, default=0.0 The PostScript character size. ps_decomposed: out, optional, type=boolean The PostScript decomposed status of the window. ps_delete: out, optional, type=boolean The delete PostScript file status of the window. ps_encapsulated: out, optional, type=boolean The PostScript encapsulated status of the window. ps_font: out, optional, type=integer The font being using for PostScript output. ps_metric: out, optional, type=boolean The metric status of the window. ps_quiet: out, optional, type=boolean Set to one of the QUIET keyword is set on PSConfig. ps_scale_factor: out, optional, type=float The PostScript scale factor. ps_tt_font: out, optional, type=string The name of the PostScript true-type font in current use. title: out, optional, type=boolean The window title. xomargin: out, optional, type=intarr(2) The !X.OMargin value for multiplots. xpos: out, optional, type=integer The X offset of the window from the upper-left corner of the display. xsize: out, optional, type=integer The starting X size of the window. yomargin: out, optional, type=intarr(2) The !Y.OMargin value for multiplots. ypos: out, optional, type=integer The Y offset of the window from the upper-left corner of the display. ysize: out, optional, type=integer The starting Y size of the window. :Examples: Used to get cgWindow global properties:: IDL> cgWindow_GetDefs, PALETTE=palette, PS_ENCAPSULATED=encap, PS_METRIC=metric :Author: FANNING SOFTWARE CONSULTING:: David W. Fanning 1645 Sheely Drive Fort Collins, CO 80526 USA Phone: 970-221-0438 E-mail: david@idlcoyote.com Coyote's Guide to IDL Programming: http://www.idlcoyote.com :History: Change History:: Written, 29 January 2011. DWF. Added PS_QUIET keyword. 17 Feb 2011. DWF. Added Raster_IM. 18 Feb 2011. Jeremy Bailin Added the ability to set and unset adjustable text size in cgWindow with ADJUSTSIZE keyword. 24 April 2011. DWF. Added PS_DECOMPOSED keyword to allow getting/setting of PostScript decomposed value. 30 Aug 2011. DWF. Added ASPECT keyword to allow getting/setting of window aspect ratio. 18 Nov 2011. DWF. Added PDF_UNIX_CONVERT_CMD and PDF_PATH keywords. 7 Dec 2011. DWF. Added IM_WIDTH keyword. 3 April 2012. DWF. Added IM_PNG8 keyword. 3 April 2012. DWF. :Copyright: Copyright (c) 2011-2012, Fanning Software Consulting, Inc.
(See $IDLUTILS_DIR/goddard/pro/coyote/cgwindow_getdefs.pro)
CGWINDOW_SETDEFS
Allows the user to set global defaults for resizeable cgWindow programs. :Categories: Graphics :Keywords: adjustsize: in, optional, type=boolean, default=0 Set this keyword to have the default text size adjusted to fit the size of the display window. aspect: in, optional, type=float, default=0.0 Set the aspect ratio of the window. If set to 0, the normal "default" window aspect ratio is used and nothing special is done when the window is resize. If aspect is not 0, then the window is confined to this aspect ratio. background: in, optional, type=string The background color of the window. Only use if the ERASEIT property is also set. delay: in, optional, type=float, default=0 Set this keyword to the amount of delay desired between command execution. 0 eraseit: in, optional, type=boolean If this property is set, the cgWindow erases with the background color before displaying the commands in the window's command list. im_density: in, optional, type=integer, default=300 Set this keyword to the sampling density when ImageMagick creates raster image file from PostScript outout. im_options: in, optional, type=string, default="" Set this keyword to any ImageMagick options you would like to pass along to the ImageMagick convert command when creating raster image files from PostScript output. im_raster: in, optional, type=boolean, default=1 (if ImageMagick is found) When raster files are created programmatically, this keyword determines if the raster file is created directly in IDL (value =0) or is created from a PostScript intermediate file via ImageMagick (value =1). The default is via ImageMagick if the convert program can be found on the machine running the program. im_resize: in, optional, type=integer, default=25 Set this keyword to percentage that the raster image file created my ImageMagick from PostScript output should be resized. im_transparent: in, optional, type=boolean, default=0 Set this keyword to allow ImageMagick to create transparent backgrounds when it makes raster image files from PostScript output. im_width: in, optional, type=integer Set this keyword to the width of the output raster file in pixel units. The height of the raster file is set to preserve the aspect ratio of the output image. Applies only to raster images (eg PNG, JPEG, TIFF, etc.) created from PostScript files with ImageMagick. multi: in, optional, type=Intarr(5) Set this keyword to the !P.MULTI setting you want to use for the window. !P.MULTI is set to this setting before command execution, and set back to it's default value when the commands are finished executing. palette: in, optional, type=byte Use this keyword to pass in an N-by-3 (or 3-by-N) byte array containing the R, G, and B vectors of a color table. It is probably easier to use cgLoadCT or XCOLORS to load color tables for the window, but this is provided as another option. pdf_path: out, optional, type=string Set this keyword to the name of the path to the Ghostscript command for converting PS to PDF. pdf_unix_convert_cmd: out, optional, type=string Set this keyword to the name of an alternative UNIX command to convert PostScript to PDF. ps_charsize: in, optional, type=float, default=0.0 Set this value to the !P.Charsize value to use when creating PostScript output. This value is not used if !P.Charsize is set to anything other than 0.0. ps_decomposed: in, optional, type=boolean If set, use decomposed color in the PostScript device. ps_delete: in, optional, type=boolean, default=1 Set this keyword to zero if you want to keep the PostScript output ImageMagick creates when making raster file output. ps_encapsulated: in, optional, type=boolean, default=0 Set this keyword to configure PSCONFIG to produce encapsulated PostScript output by default. ps_font: in, optional, type=integer, default=0 Set this to the !P.Font value to use for creating PostScript files. ps_metric: in, optional, type=boolean, default=0 Set this keyword to configure PSCONFIG to use metric values and A4 page size in its interface. ps_quiet: in, optional, type=boolean, default=0 Set this keyword to suppress output messages from PS_Start and PS_End. ps_scale_factor: in, optional, type=float, default=1.0 Set this keyword to the PostScript scale factor you want to use for PostScript output. ps_tt_font: in, optional, type=string, default="Helvetica" Set this keyword to the name of the PostScript true-type font to use for PostScript output. Not used, unless !P.Font=1. reset: in, optional, type=boolean, default=0 Set this keyword to reset all values to their default values. title: in, optional, type=boolean If this keyword is set, the selection is assumed to be a window title. All matching is done in uppercase characters. xomargin: in, optional, type=intarr(2) Set this keyword to set !X.OMargin to this value for multiplots. xpos: in, optional, type=integer Set this keyword to the X offset of the window from the upper-left corner of the display. xsize: in, optional, type=integer, default=640 Set this keyword to the starting X size of the window. yomargin: in, optional, type=intarr(2) Set this keyword to set !Y.OMargin to this value for multiplots. ypos: in, optional, type=integer Set this keyword to the Y offset of the window from the upper-left corner of the display. ysize: in, optional, type=integer, default=512 Set this keyword to the starting Y size of the window. :Examples: Used to set cgWindow global properties:: IDL> cgLoadCT, 5, RGB_TABLE=palette IDL> cgWindow_SetDefs, PALETTE=palette, $ ERASEIT=1, XSIZE=800, YSIZE=400, XPOS=100, YPOS=200, $ PS_ENCAPSULATED=1, PS_METRIC=1 IDL> cgImage, cgDemoData(7), /WINDOW, MARGIN=0.1 :Author: FANNING SOFTWARE CONSULTING:: David W. Fanning 1645 Sheely Drive Fort Collins, CO 80526 USA Phone: 970-221-0438 E-mail: david@idlcoyote.com Coyote's Guide to IDL Programming: http://www.idlcoyote.com :History: Change History:: Written, 29 January 2011. DWF. Small bug fixes, and addition of PS_QUIET keyword. 17 Feb 2011. DWF. Added Raster_IM, 18 February 2011. Jeremy Bailin. Added the ability to set and unset adjustable text size in cgWindow with ADJUSTSIZE keyword. 24 April 2011. DWF. Added PS_DECOMPOSED keyword to set the PostScript color mode. 30 Aug 2011. DWF. Added ASPECT keyword to allow getting/setting of window aspect ratio. 18 Nov 2011. DWF. Added PDF_UNIX_CONVERT_CMD and PDF_PATH keywords. 7 Dec 2011. DWF. Added IM_WIDTH keyword. 3 April 2012. DWF. Added IM_PNG8 keyword. 3 April 2012. DWF. :Copyright: Copyright (c) 2011, Fanning Software Consulting, Inc.
(See $IDLUTILS_DIR/goddard/pro/coyote/cgwindow_setdefs.pro)
CHECKSUM32
NAME: CHECKSUM32 PURPOSE: To compute the 32bit checksum of an array (ones-complement arithmetic) EXPLANATION: The 32bit checksum is adopted in the FITS Checksum convention http://heasarc.gsfc.nasa.gov/docs/heasarc/fits/checksum.html CALLING SEQUENCE: CHECKSUM32, array, checksum, [/FROM_IEEE, /NoSAVE] INPUTS: array - any numeric idl array. If the number of bytes in the array is not a multiple of four then it is padded with zeros internally (the array is returned unchanged). Convert a string array (e.g. a FITS header) to bytes prior to calling CHECKSUM32. OUTPUTS: checksum - unsigned long scalar, giving sum of array elements using ones-complement arithmetic OPTIONAL INPUT KEYWORD: /FROM_IEEE - If this keyword is set, then the input is assumed to be in big endian format (e.g. an untranslated FITS array). This keyword only has an effect on little endian machines (e.g. Linux boxes). /NoSAVE - if set, then the input array is not saved upon exiting. Use the /NoSave keyword to save time if the input array is not needed in further computations. METHOD: Uses TOTAL() to sum the array into a double precision variable. The overflow bits beyond 2^32 are then shifted back to the least significant bits. Due to the limited precision of a DOUBLE variable, the summing is done in chunks determined by MACHAR(). Adapted from FORTRAN code in heasarc.gsfc.nasa.gov/docs/heasarc/ofwg/docs/general/checksum/node30.html Could probably be done in a cleverer way (similar to the C implementation) but then the array-oriented TOTAL() function could not be used. RESTRICTIONS: (1) Not valid for object or pointer data types EXAMPLE: Find the 32 bit checksum of the array x = findgen(35) IDL> checksum32, x, s ===> s = 2920022024 FUNCTION CALLED: HOST_TO_IEEE, IS_IEEE_BIG(), N_BYTES() MODIFICATION HISTORY: Written W. Landsman June 2001 Work correctly on little endian machines, added /FROM_IEEE and /NoSave W. Landsman November 2002 Pad with zeros when array size not a multiple of 4 W.Landsman Aug 2003 Always copy to new array, somewhat slower but more robust algorithm especially for Linux boxes W. Landsman Sep. 2004 Sep. 2004 update not implemented correctly (sigh) W. Landsman Dec 2004 No need to byteswap 4 byte datatypes on little endian W. L. May 2009 Use /INTEGER keyword to TOTAL() function W.L. June 2009
(See $IDLUTILS_DIR/goddard/pro/misc/checksum32.pro)
CHECK_FITS
NAME: CHECK_FITS PURPOSE: Check that keywords in a FITS header array match the associated data EXPLANATION: Given a FITS array IM, and a associated FITS header HDR, this procedure will check that (1) HDR is a string array, and IM is defined and numeric (2) The NAXISi values in HDR are appropriate to the dimensions of IM (3) The BITPIX value in HDR is appropriate to the datatype of IM If the /UPDATE keyword is present, then the FITS header will be modified, if necessary, to force agreement with the image array CALLING SEQUENCE: check_FITS, im, hdr, [ dimen, idltype, /UPDATE, /NOTYPE, /SILENT ERRMSG = ]' INPUT PARAMETERS: IM - FITS array, e.g. as read by READFITS HDR - FITS header (string array) associated with IM OPTIONAL OUTPUTS: dimen - vector containing actual array dimensions idltype- data type of the FITS array as specified in the IDL SIZE function (1 for BYTE, 2 for INTEGER*2, 3 for INTEGER*4, etc.) OPTIONAL KEYWORD INPUTS: /NOTYPE - If this keyword is set, then only agreement of the array dimensions with the FITS header are checked, and not the data type. /UPDATE - If this keyword is set then the BITPIX, NAXIS and NAXISi FITS keywords will be updated to agree with the array /FITS, /SDAS - these are obsolete keywords that now do nothing /SILENT - If keyword is set and nonzero, the informational messages will not be printed OPTIONAL KEYWORD OUTPUT: ERRMSG = If this keyword is present, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. PROCEDURE: Program checks the NAXIS and NAXISi keywords in the header to see if they match the image array dimensions, and checks whether the BITPIX keyword agrees with the array type. PROCEDURE CALLS: FXADDPAR, FXPAR(), SXDELPAR MODIFICATION HISTORY: Written, December 1991 W. Landsman Hughes/STX to replace CHKIMHD No error returned if NAXIS=0 and IM is a scalar W. Landsman Feb 93 Fixed bug for REAL*8 STSDAS data W. Landsman July 93 Make sure NAXIS agrees with NAXISi W. Landsman October 93 Converted to IDL V5.0 W. Landsman September 1997 Allow unsigned data types W. Landsman December 1999 Allow BZERO = 0 for unsigned data types W. Landsman January 2000 Added ERRMSG keyword, W. Landsman February 2000 Use FXADDPAR to put NAXISi in proper order W. Landsman August 2000 Improper FXADDPAR call for DATATYPE keyword W. Landsman December 2000 Remove explicit setting of obsolete !err W. Landsman February 2004 Remove SDAS support W. Landsman November 2006 Fix dimension errors introduced Nov 2006 Work again for null arrays W. Landsman/E. Hivon May 2007 Use V6.0 notation W.L. Feb. 2011
(See $IDLUTILS_DIR/goddard/pro/fits/check_fits.pro)
CIC
NAME: CIC PURPOSE: Interpolate an irregularly sampled field using Cloud in Cell method EXPLANATION: This function interpolates an irregularly sampled field to a regular grid using Cloud In Cell (nearest grid point gets weight 1-dngp, point on other side gets weight dngp, where dngp is the distance to the nearest grid point in units of the cell size). CATEGORY: Mathematical functions, Interpolation CALLING SEQUENCE: Result = CIC, VALUE, POSX, NX[, POSY, NY, POSZ, NZ, AVERAGE = average, WRAPAROUND = wraparound, ISOLATED = isolated, NO_MESSAGE = no_message] INPUTS: VALUE: Array of sample weights (field values). For e.g. a temperature field this would be the temperature and the keyword AVERAGE should be set. For e.g. a density field this could be either the particle mass (AVERAGE should not be set) or the density (AVERAGE should be set). POSX: Array of X coordinates of field samples, unit indices: [0,NX>. NX: Desired number of grid points in X-direction. OPTIONAL INPUTS: POSY: Array of Y coordinates of field samples, unit indices: [0,NY>. NY: Desired number of grid points in Y-direction. POSZ: Array of Z coordinates of field samples, unit indices: [0,NZ>. NZ: Desired number of grid points in Z-direction. KEYWORD PARAMETERS: AVERAGE: Set this keyword if the nodes contain field samples (e.g. a temperature field). The value at each grid point will then be the weighted average of all the samples allocated to it. If this keyword is not set, the value at each grid point will be the weighted sum of all the nodes allocated to it (e.g. for a density field from a distribution of particles). (D=0). WRAPAROUND: Set this keyword if you want the first grid point to contain samples of both sides of the volume (see below). ISOLATED: Set this keyword if the data is isolated, i.e. not periodic. In that case total `mass' is not conserved. This keyword cannot be used in combination with the keyword WRAPAROUND. NO_MESSAGE: Suppress informational messages. Example of default allocation of nearest grid points: n0=4, *=gridpoint. 0 1 2 3 Index of gridpoints * * * * Grid points |---|---|---|---| Range allocated to gridpoints ([0.0,1.0> --> 0, etc.) 0 1 2 3 4 posx Example of ngp allocation for WRAPAROUND: n0=4, *=gridpoint. 0 1 2 3 Index of gridpoints * * * * Grid points |---|---|---|---|-- Range allocated to gridpoints ([0.5,1.5> --> 1, etc.) 0 1 2 3 4=0 posx OUTPUTS: Prints that a CIC interpolation is being performed of x samples to y grid points, unless NO_MESSAGE is set. RESTRICTIONS: Field data is assumed to be periodic with the sampled volume the basic cell, unless ISOLATED is set. All input arrays must have the same dimensions. Postition coordinates should be in `index units' of the desired grid: POSX=[0,NX>, etc. Keywords ISOLATED and WRAPAROUND cannot both be set. PROCEDURE: Nearest grid point is determined for each sample. CIC weights are computed for each sample. Samples are interpolated to the grid. Grid point values are computed (sum or average of samples). NOTES: Use tsc.pro for a higher-order interpolation scheme, ngp.pro for a lower order interpolation scheme. A standard reference for these interpolation methods is: R.W. Hockney and J.W. Eastwood, Computer Simulations Using Particles (New York: McGraw-Hill, 1981). EXAMPLE: nx=20 ny=10 posx=randomu(s,1000) posy=randomu(s,1000) value=posx^2+posy^2 field=cic(value,posx*nx,nx,posy*ny,ny,/average) surface,field,/lego MODIFICATION HISTORY: Written by Joop Schaye, Feb 1999. Avoid integer overflow for large dimensions P.Riley/W.Landsman Dec. 1999
(See $IDLUTILS_DIR/goddard/pro/math/cic.pro)
CIRRANGE
NAME: CIRRANGE PURPOSE: To force an angle into the range 0 <= ang < 360. CALLING SEQUENCE: CIRRANGE, ang, [/RADIANS] INPUTS/OUTPUT: ang - The angle to modify, in degrees. This parameter is changed by this procedure. Can be a scalar or vector. The type of ANG is always converted to double precision on output. OPTIONAL INPUT KEYWORDS: /RADIANS - If present and non-zero, the angle is specified in radians rather than degrees. It is forced into the range 0 <= ang < 2 PI. PROCEDURE: The angle is transformed between -360 and 360 using the MOD operator. Negative values (if any) are then transformed between 0 and 360 MODIFICATION HISTORY: Written by Michael R. Greason, Hughes STX, 10 February 1994. Get rid of WHILE loop, W. Landsman, Hughes STX, May 1996 Converted to IDL V5.0 W. Landsman September 1997
(See $IDLUTILS_DIR/goddard/pro/misc/cirrange.pro)
CLEANPLOT
NAME: CLEANPLOT PURPOSE: Reset all plotting system variables (!P,!X,!Y,!Z) to their default values EXPLANATION: Reset all system variables (!P,!X,!Y,!Z) which are set by the user and which affect plotting to their default values. CALLING SEQUENCE: Cleanplot, [ /Silent, /ShowOnly] INPUTS: None OPTIONAL KEYWORD INPUT: /SHOWONLY - If set, then CLEANPLOT will display the plotting system variables with nondefault values, but it will not reset them. /SILENT - If set, then CLEANPLOT will not display a message giving the the system variables tags being reset. One cannot set both /SILENT and /SHOWONLY OUTPUTS: None SIDE EFFECTS: The system variables that concern plotting are reset to their default values. A message is output for each variable changed. The !P.CLIP and CRANGE, S, WINDOW, and REGION fields of the !X, !Y, and !Z system variables are not checked since these are set by the graphics device and not by the user. PROCEDURE: This does NOT reset the plotting device. This does not change any system variables that don't control plotting. RESTRICTIONS: If user default values for !P, !X, !Y and !Z are different from the defaults adopted below, user should change P_old etc accordingly MODIFICATION HISTORY: Written IDL Version 2.3.0 W. Landsman & K. Venkatakrishna May '92 Handle new system variables in V3.0.0 W. Landsman Dec 92 Assume user has at least V3.0.0 W. Landsman August 95 V5.0 has 60 instead of 30 TICKV values W. Landsman Sep. 97 Change !D.N_COLORS to !D.TABLE_SIZE for 24 bit displays W. Landsman April 1998 Added silent keyword to supress output & modified X_old to handle the new !X and !Y tags in IDL 5.4 S. Penton July 2000 Test for visual depth if > V5.1 W. Landsman July 2000 Macs can report a visual depth of 32 W. Landsman March 2001 Call device,get_visual_depth only for device which allow it W. Landsman June 2001 Default !P.color is 16777215 for 16 bit systems W. Landsman/M. Hadfield November 2001 Added ShowOnly keyword W. Landsman April 2002 Use V6.0 notation W. Landsman April 2011
(See $IDLUTILS_DIR/goddard/pro/plot/cleanplot.pro)
CNTRD
NAME: CNTRD PURPOSE: Compute the centroid of a star using a derivative search EXPLANATION: CNTRD uses an early DAOPHOT "FIND" centroid algorithm by locating the position where the X and Y derivatives go to zero. This is usually a more "robust" determination than a "center of mass" or fitting a 2d Gaussian if the wings in one direction are affected by the presence of a neighboring star. CALLING SEQUENCE: CNTRD, img, x, y, xcen, ycen, [ fwhm , /KEEPCENTER, /SILENT, /DEBUG EXTENDBOX = ] INPUTS: IMG - Two dimensional image array X,Y - Scalar or vector integers giving approximate integer stellar center OPTIONAL INPUT: FWHM - floating scalar; Centroid is computed using a box of half width equal to 1.5 sigma = 0.637* FWHM. CNTRD will prompt for FWHM if not supplied OUTPUTS: XCEN - the computed X centroid position, same number of points as X YCEN - computed Y centroid position, same number of points as Y, floating point Values for XCEN and YCEN will not be computed if the computed centroid falls outside of the box, or if the computed derivatives are non-decreasing. If the centroid cannot be computed, then a message is displayed and XCEN and YCEN are set to -1. OPTIONAL OUTPUT KEYWORDS: /SILENT - Normally CNTRD prints an error message if it is unable to compute the centroid. Set /SILENT to suppress this. /DEBUG - If this keyword is set, then CNTRD will display the subarray it is using to compute the centroid. EXTENDBOX = {non-negative positive integer}. CNTRD searches a box with a half width equal to 1.5 sigma = 0.637* FWHM to find the maximum pixel. To search a larger area, set EXTENDBOX to the number of pixels to enlarge the half-width of the box. Default is 0; prior to June 2004, the default was EXTENDBOX= 3 /KeepCenter = By default, CNTRD finds the maximum pixel in a box centered on the input X,Y coordinates, and then extracts a new box about this maximum pixel. Set the /KeepCenter keyword to skip then step of finding the maximum pixel, and instead use a box centered on the input X,Y coordinates. PROCEDURE: Maximum pixel within distance from input pixel X, Y determined from FHWM is found and used as the center of a square, within which the centroid is computed as the value (XCEN,YCEN) at which the derivatives of the partial sums of the input image over (y,x) with respect to (x,y) = 0. In order to minimize contamination from neighboring stars stars, a weighting factor W is defined as unity in center, 0.5 at end, and linear in between RESTRICTIONS: (1) Does not recognize (bad) pixels. Use the procedure GCNTRD.PRO in this situation. (2) DAOPHOT now uses a newer algorithm (implemented in GCNTRD.PRO) in which centroids are determined by fitting 1-d Gaussians to the marginal distributions in the X and Y directions. (3) The default behavior of CNTRD changed in June 2004 (from EXTENDBOX=3 to EXTENDBOX = 0). (4) Stone (1989, AJ, 97, 1227) concludes that the derivative search algorithm in CNTRD is not as effective (though faster) as a Gaussian fit (used in GCNTRD.PRO). MODIFICATION HISTORY: Written 2/25/86, by J. K. Hill, S.A.S.C., following algorithm used by P. Stetson in DAOPHOT. Allowed input vectors G. Hennessy April, 1992 Fixed to prevent wrong answer if floating pt. X & Y supplied W. Landsman March, 1993 Convert byte, integer subimages to float W. Landsman May 1995 Converted to IDL V5.0 W. Landsman September 1997 Better checking of edge of frame David Hogg October 2000 Avoid integer wraparound for unsigned arrays W.Landsman January 2001 Handle case where more than 1 pixel has maximum value W.L. July 2002 Added /KEEPCENTER, EXTENDBOX (with default = 0) keywords WL June 2004 Some errrors were returning X,Y = NaN rather than -1,-1 WL Aug 2010
(See $IDLUTILS_DIR/goddard/pro/idlphot/cntrd.pro)
COLOR24
The purpose of this function is to convert a RGB color triple into the equivalent 24-bit long integer. The 24-bit integer can be decomposed into the appropriate color by interpreting the lowest 8 bits as red, the middle 8 bits as green, and the highest 8 bits as blue. This routine was written to be used with device-independent color programs like `cgColor`. :Categories: Graphics, Utilities :Params: color: in, required A three-element column or row array representing a color triple. Or an N-by-three element array of color triples. The values of the elements must be between 0 and 255. :Examples: To convert the color triple for the color YELLOW, (255, 255, 0), to the hexadecimal value '00FFFF'x or the decimal number 65535, type:: color = COLOR24([255, 255, 0]) :Author: FANNING SOFTWARE CONSULTING:: David W. Fanning 1645 Sheely Drive Fort Collins, CO 80526 USA Phone: 970-221-0438 E-mail: david@idlcoyote.com Coyote's Guide to IDL Programming: http://www.idlcoyote.com :History: Change History:: Written by: David Fanning, 3 February 96. Completely revised the algorithm to accept color arrays. 19 October 2000. DWF. :Copyright: Copyright (c) 1996-2012, Fanning Software Consulting, Inc.
(See $IDLUTILS_DIR/goddard/pro/coyote/color24.pro)
COLORSAREIDENTICAL
:Description: Returns a 1 if the two input colors refer to the same color, otherwise returns a 0. :Categories: Graphics Utility :Params: color_1: in, required, type=string/integer/long The first color to compare for "equality". color_2: in, required, type=string/integer/long The second color to compare for "equality". :Keywords: None. :Examples: Used to compare if two different colors are the same color:: IDL> Print, ColorsAreIdentical('white', cgColor('white')) IDL> Print, ColorsAreIdentical(252, !P.Color) IDL> Print, ColorsAreIdentical('white', '255') :Author: FANNING SOFTWARE CONSULTING:: David W. Fanning 1645 Sheely Drive Fort Collins, CO 80526 USA Phone: 970-221-0438 E-mail: david@idlcoyote.com Coyote's Guide to IDL Programming: http://www.idlcoyote.com :History: Change History:: Written, 24 December 2010. DWF. Fixed a typo when first color is INTEGER and second color is STRING. 3 Jan 2011. DWF. Added error handling for out of bounds color values. 25 May 2011. DWF. :Copyright: Copyright (c) 2010, Fanning Software Consulting, Inc.
(See $IDLUTILS_DIR/goddard/pro/coyote/colorsareidentical.pro)
COMPARE_STRUCT
NAME: COMPARE_STRUCT PURPOSE: Compare all matching tag names and return differences EXPLANATION: Compare all matching Tags names (except for "except_Tags") between two structure arrays (may have different struct.definitions), and return a structured List of fields found different. The Exelis contrib library has a faster but less powerful procedure struct_equal.pro, see http://www.exelisvis.com/Default.aspx?tabid=1540&id=1175 CALLING SEQUENCE: diff_List = compare_struct( struct_A, struct_B [ EXCEPT=, /BRIEF, /FULL, /NaN, /RECUR_A, /RECUR_B ) INPUTS: struct_A, struct_B : the two structure arrays to compare. Struct_Name : for internal recursion use only. OPTIONAL INPUT KEYWORDS: EXCEPT = string array of Tag names to ignore (NOT to compare). /BRIEF = number of differences found for each matching field of two structures is printed. /FULL = option to print even if zero differences found. /NaN = if set, then tag values are considered equal if they are both set to NaN /RECUR_A = option to search for Tag names in sub-structures of struct_A, and then call compare_struct recursively for those nested sub-structures. /RECUR_B = search for sub-structures of struct_B, and then call compare_struct recursively for those nested sub-structures. Note: compare_struct is automatically called recursively for those nested sub-structures in both struct_A and struct_B (otherwise cannot take difference) OUTPUT: Returns a structure array describing differences found. which can be examined using print,diff_List or help,/st,diff_List. The tags are TAG_NUM_A - the tag number in structure A TAG_NUM_B - the tag number in structure B FIELD - the tag name NDIFF - number of differences (always 1 for a scalar tag). PROCEDURE: Match Tag names and then use where function on tags. EXAMPLE: Find the tags in the !X system variable which are changed after a simple plot. IDL> x = !X ;Save original values IDL> plot, indgen(25) ;Make a simple plot IDL> help,/str,compare_struct(x,!X) ;See how structure has changed and one will see that the tags !X.crange and !X.S are changed by the plot. MODIFICATION HISTORY: written 1990 Frank Varosi STX @ NASA/GSFC (using copy_struct) modif Aug.90 by F.V. to check and compare same # of elements only. Added /NaN keyword W. Landsman March 2004 Don't test string for NaN values W. Landsman March 2008
(See $IDLUTILS_DIR/goddard/pro/structure/compare_struct.pro)
CONCAT_DIR()
NAME: CONCAT_DIR() PURPOSE: To concatenate directory and file names for current OS. EXPLANATION: The given file name is appended to the given directory name with the format appropriate to the current operating system. CALLING SEQUENCE: result = concat_dir( directory, file) INPUTS: directory - the directory path (string) file - the basic file name and extension (string) can be an array of filenames. OUTPUTS: The function returns the concatenated string. If the file input is a string array then the output will be a string array also. EXAMPLES: IDL> pixfile = concat_dir('$DIR_GIS_MODEL','pixels.dat') IDL> file = ['f1.dat','f2.dat','f3.dat'] IDL> dir = '$DIR_NIS_CAL' IDL> RESTRICTIONS: The version of CONCAT_DIR available at http://sohowww.nascom.nasa.gov/solarsoft/gen/idl/system/concat_dir.pro includes (mostly) additional VMS-specific keywords. CATEGORY Utilities, Strings REVISION HISTORY: Prev Hist. : Yohkoh routine by M. Morrison Written : CDS version by C D Pike, RAL, 19/3/93 Version : Version 1 19/3/93 Documentation modified Nov-94 W. Landsman Add V4.0 support for Windows W. Landsman Aug 95 Converted to IDL V5.0 W. Landsman September 1997 Changed loops to long integer W. Landsman December 1998 Added Mac support, translate Windows environment variables, & treat case where dirname ends in '/' W. Landsman Feb. 2000 Assume since V5.5, remove VMS support W. Landsman Sep. 2006
(See $IDLUTILS_DIR/goddard/pro/misc/concat_dir.pro)
CONS_DEC
NAME: CONS_DEC PURPOSE: Obtain the X and Y coordinates of a line of constant declination EXPLANATION: Returns a set of Y pixels values, given an image with astrometry, and either (1) A set of X pixel values, and a scalar declination value, or (2) A set of declination values, and a scalar X value Form (1) can be used to find the (X,Y) values of a line of constant declination. Form (2) can be used to find the Y positions of a set declinations, along a line of constant X. CALLING SEQUENCE: Y = CONS_DEC( DEC, X, ASTR, [ ALPHA ]) INPUTS: DEC - Declination value(s) in DEGREES (-!PI/2 < DEC < !PI/2). If X is a vector, then DEC must be a scalar. X - Specified X pixel value(s) for line of constant declination If DEC is a vector, then X must be a scalar. ASTR - Astrometry structure, as extracted from a FITS header by the procedure EXTAST OUTPUT: Y - Computed set of Y pixel values. The number of Y values is the same as either DEC or X, whichever is greater. OPTIONAL OUTPUT: ALPHA - the right ascensions (DEGREES) associated with the (X,Y) points RESTRICTIONS: Implemented only for the TANgent, SIN and CAR projections NOTES: The algorithm (and notation) is based on AIPS Memo 27 by Eric Greisen, with modifications for a coordinate description (CD) matrix as described in Paper II of Greisen & Calabretta (2002, A&A, 395, 1077). These documents are available from http://www.cv.nrao.edu/fits/documents/wcs/wcs.html REVISION HISTORY: Written, Wayne Landsman STX Co. April 1988 Use new astrometry structure, W. Landsman HSTX Jan. 1994 Use CD matrix, add SIN projection W. Landsman HSTX April, 1996 Converted to IDL V5.0 W. Landsman September 1997 Fix case where DEC is scalar, X is vector W. Landsman RITSS Feb. 2000 Fix possible sign error introduced Jan. 2000 W. Landsman May 2000 Work for the CARee' projection W. Landsman May 2003
(See $IDLUTILS_DIR/goddard/pro/astrom/cons_dec.pro)
CONS_RA
NAME: CONS_RA PURPOSE: Obtain the X and Y coordinates of a line of constant right ascension EXPLANATION: Return a set of X pixel values given an image with astrometry, and either (1) a set of Y pixel values, and a scalar right ascension (or longitude), or (2) a set of right ascension values, and a scalar Y value. In usage (1), CONS_RA can be used to determine the (X,Y) values of a line of constant right ascension. In usage (2), CONS_RA can used to determine the X positions of specified RA values, along a line of constant Y. CALLING SEQUENCE: X = CONS_RA( RA, Y, ASTR, [ DEC] ) INPUTS: RA - Right Ascension value in DEGREES (0 < RA < 360.). If Y is a vector, then RA must be a scalar Y - Specified Y pixel value(s) for line of constant right ascension If RA is a vector, then Y must be a scalar ASTR - Astrometry structure as extracted from a FITS header by the procedure EXTAST OUTPUTS X - Computed set of X pixel values. The number of elements of X is the maximum of the number of elements of RA and Y. OPTIONAL OUTPUT: DEC - Computed set of declinations (in DEGREES) for X,Y, coordinates NOTES: The algorithm (and notation) is based on AIPS Memo 27 by Eric Greisen, with modifications for a coordinate description (CD) matrix as described in Paper II of Calabretta & Greisen (2002, A&A, 395, 1077). These documents are available from http://www.cv.nrao.edu/fits/documents/wcs/wcs.html RESTRICTIONS: Implemented only for the TANgent, SIN and CARtesian projections REVISION HISTORY: Written, Wayne Landsman STX Co. April, 1988 Algorithm adapted from AIPS memo No. 27 by Eric Greisen New astrometry structure Converted to IDL V5.0 W. Landsman September 1997 Added SIN projection W. Landsman January 2000 Fix possible sign error introduced Jan. 2000 W. Landsman May 2000 Work for the CARee' projection W. Landsman May 2003 For TAN projection ensure angles between -90 and 90 W. Landsman Jan 2008
(See $IDLUTILS_DIR/goddard/pro/astrom/cons_ra.pro)
CONVERT_TO_TYPE
NAME: CONVERT_TO_TYPE PURPOSE: Converts its input argument to a specified data type. AUTHOR: FANNING SOFTWARE CONSULTING David Fanning, Ph.D. 1645 Sheely Drive Fort Collins, CO 80526 USA Phone: 970-221-0438 E-mail: david@idlcoyote.com Coyote's Guide to IDL Programming: http://www.idlcoyote.com CATEGORY: Utilities CALLING SEQUENCE: result = Convert_To_Type(input, type) INPUT_PARAMETERS: input: The input data to be converted. type: The data type. Accepts values as given by Size(var, /TNAME) or Size(var, /TYPE). If converting to integer types, values are truncated (similar to FLOOR keyword below), unless keywords are set. OUTPUT_PARAMETERS: result: The input data is converted to specified data type. KEYWORDS: CEILING: If set and converting to an integer type, the CEIL function is applied before conversion. FLOOR: If set and converting to an integer type, the FLOOR function is applied before conversion. ROUND: If set and converting to an integer type, the ROUND function is applied before conversion. RESTRICTIONS: Data types STRUCT, POINTER, and OBJREF are not allowed. MODIFICATION HISTORY: Written by David W. Fanning, 19 February 2006. Typo had "UNIT" instead of "UINT". 23 February 2009. DWF. Added CEILING, FLOOR, and ROUND keywords. 1 April 2009. DWF. Modified so that the "type" variable is not changed by the program. 5 May 2009. DWF.
(See $IDLUTILS_DIR/goddard/pro/coyote/convert_to_type.pro)
CONVOLVE
NAME: CONVOLVE PURPOSE: Convolution of an image with a Point Spread Function (PSF) EXPLANATION: The default is to compute the convolution using a product of Fourier transforms (for speed). The image is padded with zeros so that a large PSF does not overlap one edge of the image with the opposite edge of the image. This routine is now partially obsolete due to the introduction of the intrinsic CONVOL_FFT() function in IDL 8.1 CALLING SEQUENCE: imconv = convolve( image1, psf, FT_PSF = psf_FT ) or: correl = convolve( image1, image2, /CORREL ) or: correl = convolve( image, /AUTO ) INPUTS: image = 2-D array (matrix) to be convolved with psf psf = the Point Spread Function, (size < or = to size of image). The PSF *must* be symmetric about the point FLOOR((n_elements-1)/2), where n_elements is the number of elements in each dimension. For Gaussian PSFs, the maximum of the PSF must occur in this pixel (otherwise the convolution will shift everything in the image). OPTIONAL INPUT KEYWORDS: FT_PSF = passes out/in the Fourier transform of the PSF, (so that it can be re-used the next time function is called). FT_IMAGE = passes out/in the Fourier transform of image. /CORRELATE uses the conjugate of the Fourier transform of PSF, to compute the cross-correlation of image and PSF, (equivalent to IDL function convol() with NO rotation of PSF) /AUTO_CORR computes the auto-correlation function of image using FFT. /NO_FT overrides the use of FFT, using IDL function convol() instead. (then PSF is rotated by 180 degrees to give same result) /NO_PAD - if set, then do not pad the image to avoid edge effects. This will improve memory and speed of the computation at the expense of edge effects. This was the default method prior to October 2009 METHOD: When using FFT, PSF is centered & expanded to size of image. HISTORY: written, Frank Varosi, NASA/GSFC 1992. Appropriate precision type for result depending on input image Markus Hundertmark February 2006 Fix the bug causing the recomputation of FFT(psf) and/or FFT(image) Sergey Koposov December 2006 Fix the centering bug Kyle Penner October 2009 Add /No_PAD keyword for better speed and memory usage when edge effects are not important. W. Landsman March 2010 Add warning when kernel type does not match integer array W. Landsman Feb 2012
(See $IDLUTILS_DIR/goddard/pro/image/convolve.pro)
COPY_STRUCT
NAME: COPY_STRUCT PURPOSE: Copy all fields with matching tag names from one structure to another EXPLANATION: COPY_STRUCT is similar to the intrinisc STRUCT_ASSIGN procedure but has optional keywords to exclude or specify specific tags. Fields with matching tag names are copied from one structure array to another structure array of different type. This allows copying of tag values when equating the structures of different types is not allowed, or when not all tags are to be copied. Can also recursively copy from/to structures nested within structures. Note that the number of elements in the output structure array is automatically adjusted to equal the length of input structure array. If this not desired then use pro copy_struct_inx which allows specifying via subscripts which elements are copied where in the arrays. CALLING SEQUENCE: copy_struct, struct_From, struct_To, NT_copied copy_struct, struct_From, struct_To, EXCEPT=["image","misc"] copy_struct, struct_From, struct_To, /RECUR_TANDEM INPUTS: struct_From = structure array to copy from. struct_To = structure array to copy values to. KEYWORDS: EXCEPT_TAGS = string array of tag names to ignore (to NOT copy). Used at all levels of recursion. SELECT_TAGS = tag names to copy (takes priority over EXCEPT). This keyword is not passed to recursive calls in order to avoid the confusion of not copying tags in sub-structures. /RECUR_FROM = search for sub-structures in struct_From, and then call copy_struct recursively for those nested structures. /RECUR_TO = search for sub-structures of struct_To, and then call copy_struct recursively for those nested structures. /RECUR_TANDEM = call copy_struct recursively for the sub-structures with matching Tag names in struct_From and struct_To (for use when Tag names match but sub-structure types differ). OUTPUTS: struct_To = structure array to which new tag values are copied. NT_copied = incremented by total # of tags copied (optional) INTERNAL: Recur_Level = # of times copy_struct calls itself. This argument is for internal recursive execution only. The user call is 1, subsequent recursive calls increment it, and the counter is decremented before returning. The counter is used just to find out if argument checking should be performed, and to set NT_copied = 0 first call. EXTERNAL CALLS: pro match (when keyword SELECT_TAGS is specified) PROCEDURE: Match Tag names and then use corresponding Tag numbers. HISTORY: written 1989 Frank Varosi STX @ NASA/GSFC mod Jul.90 by F.V. added option to copy sub-structures RECURSIVELY. mod Aug.90 by F.V. adjust # elements in TO (output) to equal # elements in FROM (input) & count # of fields copied. mod Jan.91 by F.V. added Recur_Level as internal argument so that argument checking done just once, to avoid confusion. Checked against Except_Tags in RECUR_FROM option. mod Oct.91 by F.V. added option SELECT_TAGS= selected field names. mod Aug.95 by W. Landsman to fix match of a single selected tag. mod Mar.97 by F.V. do not pass the SELECT_TAGS keyword in recursion. Converted to IDL V5.0 W. Landsman September 1997 mod May 01 by D. Schlegel use long integers
(See $IDLUTILS_DIR/goddard/pro/structure/copy_struct.pro)
COPY_STRUCT_INX
NAME: COPY_STRUCT_INX PURPOSE: Copy matching tags & specified indices from one structure to another EXPLANATION: Copy all fields with matching tag names (except for "except_Tags") from one structure array to another structure array of different type. This allows copying of tag values when equating the structures of different types is not allowed, or when not all tags are to be copied. Can also recursively copy from/to structures nested within structures. This procedure is same as copy_struct with option to specify indices (subscripts) of which array elements to copy from/to. CALLING SEQUENCE: copy_struct_inx, struct_From, struct_To, NT_copied, INDEX_FROM=subf copy_struct_inx, struct_From, struct_To, INDEX_FROM=subf, INDEX_TO=subto INPUTS: struct_From = structure array to copy from. struct_To = structure array to copy values to. KEYWORDS: INDEX_FROM = indices (subscripts) of which elements of array to copy. (default is all elements of input structure array) INDEX_TO = indices (subscripts) of which elements to copy to. (default is all elements of output structure array) EXCEPT_TAGS = string array of Tag names to ignore (to NOT copy). Used at all levels of recursion. SELECT_TAGS = Tag names to copy (takes priority over EXCEPT). This keyword is not passed to recursive calls in order to avoid the confusion of not copying tags in sub-structures. /RECUR_FROM = search for sub-structures in struct_From, and then call copy_struct recursively for those nested structures. /RECUR_TO = search for sub-structures of struct_To, and then call copy_struct recursively for those nested structures. /RECUR_TANDEM = call copy_struct recursively for the sub-structures with matching Tag names in struct_From and struct_To (for use when Tag names match but sub-structure types differ). OUTPUTS: struct_To = structure array to which new tag values are copied. NT_copied = incremented by total # of tags copied (optional) INTERNAL: Recur_Level = # of times copy_struct_inx calls itself. This argument is for internal recursive execution only. The user call is 1, subsequent recursive calls increment it, and the counter is decremented before returning. The counter is used just to find out if argument checking should be performed, and to set NT_copied = 0 first call. EXTERNAL CALLS: pro match (when keyword SELECT_TAGS is specified) PROCEDURE: Match Tag names and then use corresponding Tag numbers, apply the sub-indices during = and recursion. HISTORY: adapted from copy_struct: 1991 Frank Varosi STX @ NASA/GSFC mod Aug.95 by F.V. to fix match of a single selected tag. mod Mar.97 by F.V. do not pass the SELECT_TAGS keyword in recursion, and check validity of INDEX_FROM and INDEX_TO in more detail. Converted to IDL V5.0 W. Landsman September 1997 Use long integers W. Landsman May 2001
(See $IDLUTILS_DIR/goddard/pro/structure/copy_struct_inx.pro)
CORREL_IMAGES
NAME: CORREL_IMAGES PURPOSE: Compute the 2-D cross-correlation function of two images EXPLANATION: Computes the 2-D cross-correlation function of two images for a range of (x,y) shifting by pixels of one image relative to the other. CALLING SEQUENCE: Result = CORREL_IMAGES( image_A, image_B, [XSHIFT=, YSHIFT=, XOFFSET_B=, YOFFSET_B=, REDUCTION=, MAGNIFICATION=, /NUMPIX, /MONITOR ) INPUTS: image_A, image_B = the two images of interest. OPTIONAL INPUT KEYWORDS: XSHIFT = the + & - shift to be applied in X direction, default=7. YSHIFT = the Y direction + & - shifting, default=7. XOFFSET_B = initial X pixel offset of image_B relative to image_A. YOFFSET_B = Y pixel offset, defaults are (0,0). REDUCTION = optional reduction factor causes computation of Low resolution correlation of bin averaged images, thus faster. Can be used to get approximate optimal (x,y) offset of images, and then called for successive lower reductions in conjunction with CorrMat_Analyze until REDUCTION=1, getting offset up to single pixel. MAGNIFICATION = option causes computation of high resolution correlation of magnified images, thus much slower. Shifting distance is automatically = 2 + Magnification, and optimal pixel offset should be known and specified. Optimal offset can then be found to fractional pixels using CorrMat_Analyze( correl_images( ) ). /NUMPIX - if set, causes the number of pixels for each correlation to be saved in a second image, concatenated to the correlation image, so Result is fltarr( Nx, Ny, 2 ). /MONITOR causes the progress of computation to be briefly printed. OUTPUTS: Result is the cross-correlation function, given as a matrix. PROCEDURE: Loop over all possible (x,y) shifts, compute overlap and correlation for each shift. Correlation set to zero when there is no overlap. MODIFICATION HISTORY: Written, July,1991, Frank Varosi, STX @ NASA/GSFC Use ROUND instead of NINT, June 1995, Wayne Landsman HSTX Avoid divide by zero errors, W. Landsman HSTX April 1996 Remove use of !DEBUG W. Landsman June 1997 Subtract mean of entire image before computing correlation, not just mean of overlap region H. Ebeling/W. Landsman June 1998 Always REBIN() using floating pt arithmetic W. Landsman Nov 2007
(See $IDLUTILS_DIR/goddard/pro/image/correl_images.pro)
CORREL_OPTIMIZE
NAME: CORREL_OPTIMIZE PURPOSE: Find the optimal (x,y) pixel offset of image_B relative to image_A EXPLANATION" Optimal offset is computed by means of maximizing the correlation function of the two images. CALLING SEQUENCE: CORREL_OPTIMIZE, image_A, image_B, xoffset_optimum, yoffset_optimum [ XOFF_INIT=, YOFF_INIT=, MAGNIFICATION=, /PRINT, /NUMPIX, /MONITOR, PLATEAU_THRESH= ] INPUTS: image_A, image_B = the two images of interest. OPTIONAL INPUT KEYWORDS: XOFF_INIT = initial X pixel offset of image_B relative to image_A, YOFF_INIT = Y pixel offset, (default offsets are 0 and 0). MAGNIFICATION = option to determine offsets up to fractional pixels, (example: MAG=2 means 1/2 pixel accuracy, default=1). /NUMPIX: sqrt( sqrt( # pixels )) used as correlation weighting factor. /MONITOR causes the progress of computation to be briefly printed. /PRINT causes the results of analysis to be printed. PLATEAU_THRESH = threshold used for detecting plateaus in the cross-correlation matrix near maximum, (default=0.01), used only if MAGNIFICATION > 1. Decrease this value for high signal-to-noise data OUTPUTS: xoffset_optimum = optimal X pixel offset of image_B relative to image_A. yoffset_optimum = optimal Y pixel offset. CALLS: function correl_images( image_A, image_B ) pro corrmat_analyze PROCEDURE: The combination of function correl_images( image_A, image_B ) and corrmat_analyze of the result is used to obtain the (x,y) offset yielding maximal correlation. The combination is first executed at large REDUCTION factors to speed up computation, then zooming in recursively on the optimal (x,y) offset by factors of 2. Finally, the MAGNIFICATION option (if specified) is executed to determine the (x,y) offset up to fractional pixels. MODIFICATION HISTORY: Written, July,1991, Frank Varosi, STX @ NASA/GSFC Added PLATEAU_THRESH keyword June 1997, Wayne Landsman STX Converted to IDL V5.0 W. Landsman September 1997
(See $IDLUTILS_DIR/goddard/pro/image/correl_optimize.pro)
CORRMAT_ANALYZE
NAME: CORRMAT_ANALYZE PURPOSE: Find the optimal (x,y) offset to maximize correlation of 2 images EXPLANATION: Analyzes the 2-D cross-correlation function of two images and finds the optimal(x,y) pixel offsets. Intended for use with function CORREL_IMAGES. CALLING SEQUENCE: corrmat_analyze, correl_mat, xoffset_optimum, yoffset_optimum, max_corr, edge, plateau, [XOFF_INIT=, YOFF_INIT=, REDUCTION=, MAGNIFICATION=, PLATEAU_THRESH=, /PRINT] INPUTS: correl_mat = the cross-correlation matrix of 2 images. (as computed by function CORREL_IMAGES( imA, imB ) ). NOTE: If correl_mat(*,*,1) is the number of pixels for each correlation, (the case when /NUMPIX was specified in call to CORREL_IMAGES) then sqrt( sqrt( # pixels )) is used as correlation weighting factor. OPTIONAL INPUT KEYWORDS: XOFF_INIT = initial X pixel offset of image_B relative to image_A. YOFF_INIT = Y pixel offset, (both as specified to correl_images). REDUCTION = reduction factor used in call to CORREL_IMAGES. MAGNIFICATION = magnification factor used in call to CORREL_IMAGES, this allows determination of offsets up to fractions of a pixel. PLATEAU_THRESH = threshold used for detecting plateaus in the cross-correlation matrix near maximum, (default=0.01), used only if MAGNIFICATION > 1 /PRINT causes the result of analysis to be printed. OUTPUTS: xoffset_optimum = optimal X pixel offset of image_B relative to image_A. yoffset_optimum = optimal Y pixel offset. max_corr = the maximal correlation corresponding to optimal offset. edge = 1 if maximum is at edge of correlation domain, otherwise=0. plateau = 1 if maximum is in a plateua of correlation function, else=0. PROCEDURE: Find point of maximum cross-correlation and calc. corresponding offsets. If MAGNIFICATION > 1: the correl_mat is checked for plateau near maximum, and if found, the center of plateau is taken as point of maximum cross-correlation. MODIFICATION HISTORY: Written, July-1991, Frank Varosi, STX @ NASA/GSFC Use ROUND instead of NINT, June 1995 Wayne Landsman HSTX Remove use of non-standard !DEBUG system variable W.L. HSTX Converted to IDL V5.0 W. Landsman September 1997
(See $IDLUTILS_DIR/goddard/pro/image/corrmat_analyze.pro)
COSMO_PARAM
NAME: COSMO_PARAM PURPOSE: Derive full set of cosmological density parameters from a partial set EXPLANATION: This procedure is called by LUMDIST and GALAGE to allow the user a choice in defining any two of four cosmological density parameters. Given any two of the four input parameters -- (1) the normalized matter density Omega_m (2) the normalized cosmological constant, Omega_lambda (3) the normalized curvature term, Omega_k and (4) the deceleration parameter q0 -- this program will derive the remaining two. Here "normalized" means divided by the closure density so that Omega_m + Omega_lambda + Omega_k = 1. For a more precise definition see Carroll, Press, & Turner (1992, ArAA, 30, 499). If less than two parameters are defined, this procedure sets default values of Omega_k=0 (flat space), Omega_lambda = 0.7, Omega_m = 0.3 and q0 = -0.55 CALLING SEQUENCE: COSMO_PARAM, Omega_m, Omega_lambda, Omega_k, q0 INPUT-OUTPUTS: Omega_M - normalized matter energy density, non-negative numeric scalar Omega_Lambda - Normalized cosmological constant, numeric scalar Omega_k - normalized curvature parameter, numeric scalar. This is zero for a flat universe q0 - Deceleration parameter, numeric scalar = -R*(R'')/(R')^2 = 0.5*Omega_m - Omega_lambda NOTES: If more than two parameters are defined upon input (overspecification), then the first two defined parameters in the ordered list Omega_m, Omega_lambda, Omega_k, q0 are used to define the cosmology. EXAMPLE: Suppose one has Omega_m = 0.3, and Omega_k = 0.5 then to determine Omega_lambda and q0 IDL> cosmo_param, 0.3, omega_lambda, 0.5, q0 which will return omega_lambda = 0.2 and q0 = -2.45 REVISION HISTORY: W. Landsman Raytheon ITSS April 2000 Better Error checking W. Landsman/D. Syphers October 2010
(See $IDLUTILS_DIR/goddard/pro/astro/cosmo_param.pro)
COYOTEGRAPHIC
This simple just identifies a routine as a Coyote Graphic routine. It is written primarily so I can identify such routines before I assign a background color to a graphics window. :Categories: Graphics :Examples: Used in graphics programs:: IDL> IF CoyoteGraphic() THEN background = 'white' :Author: FANNING SOFTWARE CONSULTING:: David W. Fanning 1645 Sheely Drive Fort Collins, CO 80526 USA Phone: 970-221-0438 E-mail: david@idlcoyote.com Coyote's Guide to IDL Programming: http://www.idlcoyote.com :History: Change History:: Written, 18 January 2011. DWF. :Copyright: Copyright (c) 2011, Fanning Software Consulting, Inc.
(See $IDLUTILS_DIR/goddard/pro/coyote/coyotegraphic.pro)
CO_ABERRATION
NAME: CO_ABERRATION PURPOSE: Calculate changes to Ra and Dec due to "the effect of aberration", EXPLANATION: as described in Meeus, Chap 23. CALLING SEQUENCE: co_aberration, jd, ra, dec, d_ra, d_dec, [EPS = ] INPUTS jd : Julian Date [scalar or vector] ra, dec : Arrays (or scalars) of the ra and dec's in degrees Note: if jd is a vector, ra and dec MUST be vectors of the same length. OUTPUTS d_ra, d_dec: the corrections to ra and dec due to aberration (must then be added to ra and dec to get corrected values). OPTIONAL INPUT KEYWORD: eps : set this to the true obliquity of the ecliptic (in radians), or it will be set for you if you don't know it (in that case, set it to an empty variable). EXAMPLE: Compute the change in RA and Dec of Theta Persei (RA = 2h46m,11.331s, Dec = 49d20',54.54" on 2028 Nov 13.19 TD IDL> jdcnv,2028,11,13,.19*24,jd ;Get Julian date IDL> co_aberration,jd,ten(2,46,11.331)*15,ten(49,20,54.54),d_ra,d_dec ==> d_ra = 30.045" d_dec = 6.697" NOTES: These formula are from Meeus, Chapters 23. Accuracy is much better than 1 arcsecond. REVISION HISTORY: Written, June 2002, Chris O'Dell, U. of Wisconsin Fix error with vector input W. Landsman June 2009
(See $IDLUTILS_DIR/goddard/pro/astro/co_aberration.pro)
CO_NUTATE
NAME: CO_NUTATE PURPOSE: Calculate changes in RA and Dec due to nutation of the Earth's rotation EXPLANATION: Calculates necessary changes to ra and dec due to the nutation of the Earth's rotation axis, as described in Meeus, Chap 23. Uses formulae from Astronomical Almanac, 1984, and does the calculations in equatorial rectangular coordinates to avoid singularities at the celestial poles. CALLING SEQUENCE: CO_NUTATE, jd, ra, dec, d_ra, d_dec, [EPS=, D_PSI =, D_EPS = ] INPUTS JD: Julian Date [scalar or vector] RA, DEC : Arrays (or scalars) of the ra and dec's of interest Note: if jd is a vector, ra and dec MUST be vectors of the same length. OUTPUTS: d_ra, d_dec: the corrections to ra and dec due to nutation (must then be added to ra and dec to get corrected values). OPTIONAL OUTPUT KEYWORDS: EPS: set this to a named variable that will contain the obliquity of the ecliptic. D_PSI: set this to a named variable that will contain the nutation in the longitude of the ecliptic D_EPS: set this to a named variable that will contain the nutation in the obliquity of the ecliptic EXAMPLE: (1) Example 23a in Meeus: On 2028 Nov 13.19 TD the mean position of Theta Persei is 2h 46m 11.331s 49d 20' 54.54". Determine the shift in position due to the Earth's nutation. IDL> jd = JULDAY(11,13,2028,.19*24) ;Get Julian date IDL> CO_NUTATE, jd,ten(2,46,11.331)*15.,ten(49,20,54.54),d_ra,d_dec ====> d_ra = 15.843" d_dec = 6.217" PROCEDURES USED: NUTATE REVISION HISTORY: Written Chris O'Dell, 2002 Vector call to NUTATE W. Landsman June 2002
(See $IDLUTILS_DIR/goddard/pro/astro/co_nutate.pro)
CO_REFRACT()
NAME: CO_REFRACT() PURPOSE: Calculate correction to altitude due to atmospheric refraction. DESCRIPTION: CO_REFRACT can calculate both apparent altitude from observed altitude and vice-versa. CALLING SEQUENCE: new_alt = CO_REFRACT(old_alt, [ ALTITUDE= , PRESSURE= , $ TEMPERATURE= , /TO_OBSERVED , EPSILON= ]) INPUT: old_alt - Observed (apparent) altitude, in DEGREES. (apparent if keyword /TO_OBSERVED set). May be scalar or vector. OUTPUT: Function returns apparent (observed) altitude, in DEGREES. (observed if keyword /TO_OBSERVED set). Will be of same type as input altitude(s). OPTIONAL KEYWORD INPUTS: ALTITUDE : The height of the observing location, in meters. This is only used to determine an approximate temperature and pressure, if these are not specified separately. [default=0, i.e. sea level] PRESSURE : The pressure at the observing location, in millibars. TEMPERATURE: The temperature at the observing location, in Kelvin. EPSILON: When keyword /TO_OBSERVED has been set, this is the accuracy to obtain via the iteration, in arcseconds [default = 0.25 arcseconds]. /TO_OBSERVED: Set this keyword to go from Apparent->Observed altitude, using the iterative technique. Note, if altitude is set, but temperature or pressure are not, the program will make an intelligent guess for the temperature and pressure. DESCRIPTION: Because the index of refraction of air is not precisely 1.0, the atmosphere bends all incoming light, making a star or other celestial object appear at a slightly different altitude (or elevation) than it really is. It is important to understand the following definitions: Observed Altitude: The altitude that a star is SEEN to BE, with a telescope. This is where it appears in the sky. This is always GREATER than the apparent altitude. Apparent Altitude: The altitude that a star would be at, if *there were no atmosphere* (sometimes called "true" altitude). This is usually calculated from an object's celestial coordinates. Apparent altitude is always LOWER than the observed altitude. Thus, for example, the Sun's apparent altitude when you see it right on the horizon is actually -34 arcminutes. This program uses couple simple formulae to estimate the effect for most optical and radio wavelengths. Typically, you know your observed altitude (from an observation), and want the apparent altitude. To go the other way, this program uses an iterative approach. EXAMPLE: The lower limb of the Sun is observed to have altitude of 0d 30'. Calculate the the true (=apparent) altitude of the Sun's lower limb using mean conditions of air pressure and temperature IDL> print, co_refract(0.5) ===> 0.025degrees (1.55') WAVELENGTH DEPENDENCE: This correction is 0 at zenith, about 1 arcminute at 45 degrees, and 34 arcminutes at the horizon FOR OPTICAL WAVELENGTHS. The correction is NON-NEGLIGIBLE at all wavelengths, but is not very easily calculable. These formulae assume a wavelength of 550 nm, and will be accurate to about 4 arcseconds for all visible wavelengths, for elevations of 10 degrees and higher. Amazingly, they are also ACCURATE FOR RADIO FREQUENCIES LESS THAN ~ 100 GHz. It is important to understand that these formulae really can't do better than about 30 arcseconds of accuracy very close to the horizon, as variable atmospheric effects become very important. REFERENCES: 1. Meeus, Astronomical Algorithms, Chapter 15. 2. Explanatory Supplement to the Astronomical Almanac, 1992. 3. Methods of Experimental Physics, Vol 12 Part B, Astrophysics, Radio Telescopes, Chapter 2.5, "Refraction Effects in the Neutral Atmosphere", by R.K. Crane. DEPENDENCIES: CO_REFRACT_FORWARD (contained in this file and automatically compiled). AUTHOR: Chris O'Dell Univ. of Wisconsin-Madison Observational Cosmology Laboratory Email: odell@cmb.physics.wisc.edu REVISION HISTORY: version 1 (May 31, 2002) Update iteration formula, W. Landsman June 2002 Corrected slight bug associated with scalar vs. vector temperature and pressure inputs. 6/10/2002 Fixed problem with vector input when /TO_OBSERVED set W. Landsman Dec 2005 Allow arrays with more than 32767 elements W.Landsman/C.Dickinson Feb 2010
(See $IDLUTILS_DIR/goddard/pro/astro/co_refract.pro)
CREATE_STRUCT
NAME: CREATE_STRUCT PURPOSE: Create an IDL structure from a list of tag names and dimensions EXPLANATION: Dynamically create an IDL structure variable from list of tag names and data types of arbitrary dimensions. Useful when the type of structure needed is not known until run time. Unlike the intrinsic function CREATE_STRUCT(), this procedure does not require the user to know the number of tags before run time. (Note there is no name conflict since the intrinsic CREATE_STRUCT is a function, and this file contains a procedure.) CALLING SEQUENCE: CREATE_STRUCT, STRUCT, strname, tagnames, tag_descript, [ DIMEN = , /CHATTER, /NODELETE ] INPUTS: STRNAME - name to be associated with structure (string) Must be unique for each structure created. Set STRNAME = '' to create an anonymous structure TAGNAMES - tag names for structure elements (string or string array) Any strings that are not valid IDL tag names (e.g. 'a\2') will be converted by IDL_VALIDNAME to a valid tagname by replacing with underscores as necessary (e.g. 'a_2') TAG_DESCRIPT - String descriptor for the structure, containing the tag type and dimensions. For example, 'A(2),F(3),I', would be the descriptor for a structure with 3 tags, strarr(2), fltarr(3) and Integer scalar, respectively. Allowed types are 'A' for strings, 'B' or 'L' for unsigned byte integers, 'I' for integers, 'J' for longword integers, 'K' for 64bit integers, 'F' or 'E' for floating point, 'D' for double precision 'C' for complex, and 'M' for double complex. Uninterpretable characters in a format field are ignored. For vectors, the tag description can also be specified by a repeat count. For example, '16E,2J' would specify a structure with two tags, fltarr(16), and lonarr(2) OPTIONAL KEYWORD INPUTS: DIMEN - number of dimensions of structure array (default is 1) CHATTER - If set, then CREATE_STRUCT() will display the dimensions of the structure to be created, and prompt the user whether to continue. Default is no prompt. /NODELETE - If set, then the temporary file created CREATE_STRUCT will not be deleted upon exiting. See below OUTPUTS: STRUCT - IDL structure, created according to specifications EXAMPLES: IDL> create_struct, new, 'name',['tag1','tag2','tag3'], 'D(2),F,A(1)' will create a structure variable new, with structure name NAME To see the structure of new: IDL> help,new,/struc ** Structure NAME, 3 tags, 20 length: TAG1 DOUBLE Array(2) TAG2 FLOAT 0.0 TAG3 STRING Array(1) PROCEDURE: Generates a temporary procedure file using input information with the desired structure data types and dimensions hard-coded. This file is then executed with CALL_PROCEDURE. NOTES: If CREATE_STRUCT cannot write a temporary .pro file in the current directory, then it will write the temporary file in the getenv('HOME') directory. Note that 'L' now specifies a LOGICAL (byte) data type and not a a LONG data type for consistency with FITS binary tables RESTRICTIONS: The name of the structure must be unique, for each structure created. Otherwise, the new variable will have the same structure as the previous definition (because the temporary procedure will not be recompiled). ** No error message will be generated *** SUBROUTINES CALLED: REPCHR() MODIFICATION HISTORY: Version 1.0 RAS January 1992 Modified 26 Feb 1992 for Rosat IDL Library (GAR) Modified Jun 1992 to accept arrays for tag elements -- KLV, Hughes STX Accept anonymous structures W. Landsman HSTX Sep. 92 Accept 'E' and 'J' format specifications W. Landsman Jan 93 'L' format now stands for logical and not long array Accept repeat format for vectors W. Landsman Feb 93 Accept complex and double complex (for V4.0) W. Landsman Jul 95 Work for long structure definitions W. Landsman Aug 97 Write temporary file in HOME directory if necessary W. Landsman Jul 98 Use OPENR,/DELETE for OS-independent file removal W. Landsman Jan 99 Use STRSPLIT() instead of GETTOK() W. Landsman July 2002 Assume since V5.3 W. Landsman Feb 2004 Added RESOLVE_ROUTINE to ensure recompilation W. Landsman Sep. 2004 Delete temporary with FILE_DELETE W. Landsman Sep 2006 Assume since V5.5, delete VMS reference W.Landsman Sep 2006 Added 'K' format for 64 bit integers, IDL_VALIDNAME check on tags W. Landsman Feb 2007 Use vector form of IDL_VALIDNAME() if V6.4 or later W.L. Dec 2007 Suppress compilation mesage of temporary file A. Conley/W.L. May 2009 Remove FDECOMP, some cleaner coding W.L. July 2009 Do not limit string length to 1000 chars P. Broos, Feb 2011
(See $IDLUTILS_DIR/goddard/pro/structure/create_struct.pro)
CR_REJECT
NAME: CR_REJECT PURPOSE: General, iterative cosmic ray rejection using two or more input images. EXPLANATION: Uses a noise model input by the user, rather than determining noise empirically from the images themselves. The image returned has the combined exposure time of all the input images, unless the bias flag is set, in which case the mean is returned. This image is computed by summation (or taking mean) regardless of loop and initialization options (see below). CALLING SEQUENCE: cr_reject, input_cube, rd_noise_dn, dark_dn, gain, mult_noise, $ combined_image, combined_npix, combined_noise MODIFIED ARGUMENT: input_cube - Cube in which each plane is an input image. If the noise model is used (rd_noise_dn, dark_dn, gain), then input_cube must be in units of DN. If an input noise cube is supplied (rd_noise_dn <0), then the units of input_cube and noise_cube merely need to be consistent. This array is used as a buffer and its contents are not guaranteed on output (although for now, weighting=0 with /restore_sky should give you back your input unaltered). INPUT ARGUMENTS: rd_noise_dn - Read noise per pixel. Units are DN. If negative, then the user supplies an error cube via the keyword noise_cube. In the latter case, mult_noise still applies, since it is basically a fudge. dark_dn - Dark rate in DN per pixel per s. This can be a scalar, or it can be a dark image divided by the exposure time. gain - Electrons per DN. mult_noise - Coefficient for multiplicative noise term -- helps account for differing PSFs or subpixel image shifts. INPUT KEYWORDS: exptime - If the images have different exposure times, pass them in a vector. You can leave this off for frames with the same exposure time, but dark counts won't be treated correctly. verbose - If set, lots of output. nsig - Rejection limit in units of pixel-to-pixel noise (sigma) on each input image. Can be specified as an array, in which case the dimension gives the maximum number of iterations to run. (Default = [8, 6, 4] dilation - With dfactor, provides functionality similar to the expansion of the CR with pfactor and radius in STSDAS crrej. Dilate gives the size of the border to be tested around each initially detected CR pixel. E.g., dilate=1 searches a 9 X 9 area centered on the original pixel. If dfactor is set, the default is 1. dfactor - See dilation. This parameter is equivalent to pfactor in STSDAS crrej. The current threshold for rejection is multiplied by this factor when doing the search with the dilated mask. If dilation is set, the default for this parameter is 0.5. bias - Set if combining biases (divides through by number of images at end, since exposure time is 0). tracking_set - Subscripts of pixels to be followed through the computation. noskyadjust - Sky not to be subtracted before rejection tests. Default is to do the subtraction. xmedsky - Flag. If set, the sky is computed as a 1-d array which is a column-by-column median. This is intended for STIS slitless spectra. If sky adjustment is disabled, this keyword has no effect. input_mask - Mask cube input by the user. Should be byte data because it's boolean. 1 means use the pixel, and 0 means reject the pixel - these rejections are in addition to those done by the CR rejection algorithm as such. The following keywords control how the current guess at a CR-free "check image" is recomputed on each iteration: median_loop - If set, the check image for each iteration is the pixel-by-pixel median. THE MEAN IS RETURNED in combined_image even if you set this option. (Default is mean_loop.) minimum_loop - If set, the check image for each iteration is the pixel-by-pixel minimum. THE MEAN IS RETURNED in combined_image even if you set this option. (Default is mean_loop.) mean_loop - If set, the check image for each iteration is the pixel-by-pixel mean. (Same as the default.) noclearmask - By default, the mask of CR flags is reset before every iteration, and a pixel that has been rejected has a chance to get back in the game if the average migrates toward its value. If this keyword is set, then any rejected pixel stays rejected in subsequent iterations. Note that what stsdas.hst_calib.wfpc.crrej does is the same as the default. For this procedure, the default was NOT to clear the flags, until 20 Oct. 1997. restore_sky - Flag. If set, the routine adds the sky back into input_cube before returning. Works only if weighting=0. null_value - Value to be used for output pixels to which no input pixels contribute. Default=0 weighting - Selects weighting scheme in final image combination: 0 (default) - Poissonian weighting - co-add detected DN from non-CR pixels. (Pixel-by- pixel scaling up to total exposure time, for pixels in stack where some rejected.) Equivalent to exptime weighting of rates. 1 or more - Sky and read noise weighting of rates. Computed as weighted average of DN rates, with total exp time multiplied back in afterward. In all cases, the image is returned as a sum in DN with the total exposure time of the image stack, and with total sky added back in. The following keywords allow the initial guess at a CR-free "check image" to be of a different kind from the iterative guesses: init_med - If set, the initial check image is the pixel-by-pixel median. (Not permitted if input_cube has fewer than 3 planes; default is minimum.) init_mean - If set, the initial check image is the pixel-by-pixel mean. (Default is minimum.) init_min - If set, the initial check image is the pixel-by-pixel minimum. (Same as the default.) OUTPUT ARGUMENTS:: combined_image - Mean image with CRs removed. combined_npix - Byte (or integer) image of same dimensions as combined_image, with each element containing the number of non-CR stacked pixels that went into the result. combined_noise - Noise in combined image according to noise model or supplied noise cube. OUTPUT KEYWORDS: mask_cube - CR masks for each input image. 1 means good pixel; 0 means CR pixel. skyvals - Sky value array. For an image cube with N planes, this array is fltarr(N) if the sky is a scalar per image plane, and fltarr(XDIM, N), is the XMEDSKY is set. INPUT/OUTPUT KEYWORD: noise_cube - Estimated noise in each pixel of input_cube as returned (if rd_noise_dn ge 0), or input noise per pixel of image_cube (if rd_noise_dn lt 0). skybox - X0, X1, Y0, Y1 bounds of image section used to compute sky. If supplied by user, this region is used. If not supplied, the image bounds are returned. This parameter might be used (for instance) if the imaging area doesn't include the whole chip. COMMON BLOCKS: none SIDE EFFECTS: none METHOD: COMPARISON WITH STSDAS Cr_reject emulates the crrej routine in stsdas.hst_calib.wfpc. The two routines have been verified to give identical results (except for some pixels along the edge of the image) under the following conditions: no sky adjustment no dilation of CRs initialization of trial image with minimum taking mean for each trial image after first (no choice in crrej) Dilation introduces a difference between crrej and this routine around the very edge of the image, because the IDL mask manipulation routines don't handle the edge the same way as crrej does. Away from the edge, crrej and cr_reject are the same with respect to dilation. The main difference between crrej and cr_reject is in the sky computation. Cr_reject does a DAOPHOT I sky computation on a subset of pixels grabbed from the image, whereas crrej searches for a histogram mode. REMARKS ON USAGE The default is that the initial guess at a CR-free image is the pixel-by-pixel minimum of all the input images. The pixels cut from each component image are the ones more than nsig(0) sigma from this minimum image. The next iteration is based on the mean of the cleaned-up component images, and the cut is taken at nsig(1) sigma. The next iteration is also based on the mean with the cut taken at nsig(2) sigma. The user can specify an arbitrary sequence of sigma cuts, e.g., nsig=[6,2] or nsig=[10,9,8,7]. The user can also specify that the initial guess is the median (/init_med) rather than the minimum, or even the mean. The iterated cleaned_up images after the first guess can be computed as the mean or the median (/mean_loop or /median_loop). The minimum_loop option is also specified, but this is a trivial case, and you wouldn't want to use it except perhaps for testing. The routine takes into account exposure time if you want it to, i.e., if the pieces of the CR-split aren't exactly the same. For bias frames (exposure time 0), set /bias to return the mean rather than the total of the cleaned-up component images. The crrej pfactor and radius to propagate the detected CRs outward from their initial locations have been implemented in slightly different form using the IDL DILATE function. It is possible to end up with output pixels to which no valid input pixels contribute. These end up with the value NULL_VALUE, and the corresponding pixels of combined_npix are also returned as 0. This result can occur when the pixel is very noisy across the whole image stack, i.e., if all the values are, at any step of the process, far from the stack average at that position even after rejecting the real outliers. Because pixels are flagged symmetrically N sigma above and below the current combined image (see code), all the pixels at a given position can end up getting flagged. (At least, that's how I think it happens.) MODIFICATION HISTORY: 5 Mar. 1997 - Written. R. S. Hill 14 Mar. 1997 - Changed to masking approach to keep better statistics and return CR-affected pixels to user. Option to track subset of pixels added. Dilation of initially detected CRs added. Other small changes. RSH 17 Mar. 1997 - Arglist and treatment of exposure times fiddled to mesh better with stis_cr. RSH 25 Mar. 1997 - Fixed bug if dilation finds nothing. RSH 4 Apr. 1997 - Changed name to cr_reject. RSH 15 Apr. 1997 - Restyled with emacs, nothing else done. RSH 18 Jun. 1997 - Input noise cube allowed. RSH 19 Jun. 1997 - Multiplicative noise deleted from final error. RSH 20 Jun. 1997 - Fixed error in using input noise cube. RSH 12 July 1997 - Sky adjustment option. RSH 27 Aug. 1997 - Dilation kernel made round, not square, and floating-point radius allowed. RSH 16 Sep. 1997 - Clearmask added. Intermediate as well as final mean is exptime weighted. RSH 17 Sep. 1997 - Redundant zeroes around dilation kernel trimmed. RSH 1 Oct. 1997 - Bugfix in preceding. RSH 21 Oct. 1997 - Clearmask changed to noclearmask. Bug in robust array division fixed (misplaced parens). Sky as a function of X (option). RSH 30 Jan. 1998 - Restore_sky keyword added. RSH 5 Feb. 1998 - Quick help corrected and updated. RSH 6 Feb. 1998 - Fixed bug in execution sequence for tracking_set option. RSH 18 Mar. 1998 - Eliminated confusing maxiter spec. Added null_value keyword. RSH 15 May 1998 - Input_mask keyword. RSH 27 May 1998 - Initialization of minimum image corrected. NRC, RSH 9 June 1998 - Input mask cube processing corrected. RSH 21 Sep. 1998 - Weighting keyword added. RSH 7 Oct. 1998 - Fixed bug in input_mask processing (introduced in preceding update). Input_mask passed to skyadj_cube. RSH 5 Mar. 1999 - Force init_min for 2 planes. RSH 1 Oct. 1999 - Make sure weighting=1 not given with noise cube. RSH 1 Dec. 1999 - Corrections to doc; restore_sky needs weighting=0. RSH 17 Mar. 2000 - SKYBOX added. RSH
(See $IDLUTILS_DIR/goddard/pro/image/cr_reject.pro)
CSPLINE
NAME: CSPLINE PURPOSE: Function to evaluate a natural cubic spline at specified data points EXPLANATION: Combines the Numerical Recipes functions SPL_INIT and SPL_INTERP CALLING SEQUENCE: result = cspline( x, y, t, [ DERIV = ]) INPUTS: x - vector of spline node positions, must be monotonic increasing or decreasing y - vector of node values t - x-positions at which to evaluate the spline, scalar or vector INPUT-OUTPUT KEYWORD: DERIV - values of the second derivatives of the interpolating function at the node points. This is an intermediate step in the computation of the natural spline that requires only the X and Y vectors. If repeated interpolation is to be applied to the same (X,Y) pair, then some computation time can be saved by supplying the DERIV keyword on each call. On the first call DERIV will be computed and returned on output. OUTPUT: the values for positions t are returned as the function value If any of the input variables are double precision, then the output will also be double precision; otherwise the output is floating point. EXAMPLE: The following uses the example vectors from the SPL_INTERP documentation IDL> x = (findgen(21)/20.0)*2.0*!PI ;X vector IDL> y = sin(x) ;Y vector IDL> t = (findgen(11)/11.0)*!PI ;Values at which to interpolate IDL> cgplot,x,y,psym=1 ;Plot original grid IDL> cgplot, /over, t,cspline(x,y,t),psym=2 ;Overplot interpolated values METHOD: The "Numerical Recipes" implementation of the natural cubic spline is used, by calling the intrinsic IDL functions SPL_INIT and SPL_INTERP. HISTORY: version 1 D. Lindler May, 1989 version 2 W. Landsman April, 1997 Rewrite using the intrinsic SPL_INIT & SPL_INTERP functions Converted to IDL V5.0 W. Landsman September 1997 Work for monotonic decreasing X vector W. Landsman February 1999
(See $IDLUTILS_DIR/goddard/pro/math/cspline.pro)
CT2LST
NAME: CT2LST PURPOSE: To convert from Local Civil Time to Local Mean Sidereal Time. CALLING SEQUENCE: CT2LST, Lst, Lng, Tz, Time, [Day, Mon, Year] or CT2LST, Lst, Lng, dummy, JD INPUTS: Lng - The longitude in degrees (east of Greenwich) of the place for which the local sidereal time is desired, scalar. The Greenwich mean sidereal time (GMST) can be found by setting Lng = 0. Tz - The time zone of the site in hours, positive East of the Greenwich meridian (ahead of GMT). Use this parameter to easily account for Daylight Savings time (e.g. -4=EDT, -5 = EST/CDT), scalar This parameter is not needed (and ignored) if Julian date is supplied. ***Note that the sign of TZ was changed in July 2008 to match the standard definition.*** Time or JD - If more than four parameters are specified, then this is the time of day of the specified date in decimal hours. If exactly four parameters are specified, then this is the Julian date of time in question, scalar or vector OPTIONAL INPUTS: Day - The day of the month (1-31),integer scalar or vector Mon - The month, in numerical format (1-12), integer scalar or vector Year - The 4 digit year (e.g. 2008), integer scalar or vector OUTPUTS: Lst The Local Sidereal Time for the date/time specified in hours. RESTRICTIONS: If specified, the date should be in numerical form. The year should appear as yyyy. PROCEDURE: The Julian date of the day and time is question is used to determine the number of days to have passed since 0 Jan 2000. This is used in conjunction with the GST of that date to extrapolate to the current GST; this is then used to get the LST. See Astronomical Algorithms by Jean Meeus, p. 84 (Eq. 11-4) for the constants used. EXAMPLE: Find the Greenwich mean sidereal time (GMST) on 2008 Jul 30 at 15:53 pm in Baltimore, Maryland (longitude=-76.72 degrees). The timezone is EDT or tz=-4 IDL> CT2LST, lst, -76.72, -4,ten(15,53), 30, 07, 2008 ==> lst = 11.356505 hours (= 11h 21m 23.418s) The Web site http://tycho.usno.navy.mil/sidereal.html contains more info on sidereal time, as well as an interactive calculator. PROCEDURES USED: jdcnv - Convert from year, month, day, hour to julian date MODIFICATION HISTORY: Adapted from the FORTRAN program GETSD by Michael R. Greason, STX, 27 October 1988. Use IAU 1984 constants Wayne Landsman, HSTX, April 1995, results differ by about 0.1 seconds Longitudes measured *east* of Greenwich W. Landsman December 1998 Time zone now measure positive East of Greenwich W. Landsman July 2008 Remove debugging print statement W. Landsman April 2009
(See $IDLUTILS_DIR/goddard/pro/astro/ct2lst.pro)
CURS
NAME: CURS PURPOSE: Selects an X windows cursor shape CALLING SEQUENCE: curs ;Interactively select a cursor shape. curs, sel ;Make the given CURSOR_STANDARD value the cursor shape. OPTIONAL INPUT: sel - Either an integer giving the CURSOR_STANDARD value (usually an even value between 0 and 152) indicating the cursor shape, or a string from the following menu a -- Up arrow b -- Left-angled arrow c -- Right-angled arrow d -- Crosshair e -- Finger pointing left f -- Finger pointing right g -- Narrow crosshair h -- Cycle through all possible standard cursor shapes The full list of available cursor values is given in /usr/include/X11/cursorfont.h OUTPUTS: None. RESTRICTIONS: Uses the CURSOR_STANDARD keyword of the DEVICE procedure. Although this keyword is available in Windows IDL, the values used by this procedure are specific to the X windows device. PROCEDURE: If the user supplies a valid cursor shape value, it is set. Otherwise, an interactive command loop is entered; it will continue until a valid value is given. MODIFICATION HISTORY: Converted to VAX 3100 workstations / IDL V2. M. Greason, STX, May 1990. Avoid bad cursor parameter values W. Landsman February, 1991 Don't change value of input param W. Landsman August 1995 Use SIZE(/TNAME) instead of DATATYPE() W. Landsman October 2001
(See $IDLUTILS_DIR/goddard/pro/tv/curs.pro)
CURVAL
NAME: CURVAL PURPOSE: Cursor controlled display of image intensities and astronomical coords EXPLANATION CURVAL displays different information depending whether the user supplied an image array, and/or a FITS header array Note that in the usual truecolor mode, the byte intensity returned by CURVAL does not correspond to the byte scaled image value but rather returns the maximum value in each color gun. CALLING SEQUENCE(S): curval ;Display x,y and byte intensity (inten) curval, im ;Display x,y,inten, and also pixel value (from image array) curval, hdr, [ im, OFFSET= , ZOOM=, FILENAME=, ALT=] OPTIONAL INPUTS: Hdr = FITS Header array Im = Array containing values that are displayed. Any type. OPTIONAL KEYWORD INPUTS: ALT - single character 'A' through 'Z' or ' ' specifying an alternate astrometry system present in the FITS header. The default is to use the primary astrometry or ALT = ' '. If /ALT is set, then this is equivalent to ALT = 'A'. See Section 3.3 of Greisen & Calabretta (2002, A&A, 395, 1061) for information about alternate astrometry keywords. OFFSET - 2 element vector giving the location of the image pixel (0,0) on the window display. OFFSET can be positive (e.g if the image is centered in a larger window) or negative (e.g. if the only the central region of an image much larger than the window is being displayed. Default value is [0,0], or no offset. ZOOM - Scalar specifying the magnification of the window with respect to the image variable. Use, for example, if image has been REBINed before display. FILENAME = name of file to where CURVAL data can be saved. Data will only be saved if left or center mouse button are pressed. OUTPUTS: None. SIDE EFFECTS: X and Y values, etc., of the pixel under the cursor are constantly displayed. Pressing left or center mouse button prints a line of output, and starts a new line. Pressing right mouse button exits the procedure. If the keyword FILENAME is defined, the date and time, and a heading will be printed in the file before the data. PROCEDURES CALLED: ADSTRING(), EXTAST, GSSSXYAD, RADEC, SXPAR(), UNZOOM_XY, XY2AD REVISION HISTORY: Written, K. Rhode, STX May 1990 Added keyword FILENAME D. Alexander June 1991 Don't write to Journal file W. Landsman March 1993 Use astrometry structure W. Landsman Feb 1994 Modified for Mac IDL I. Freedman April 1994 Allow for zoomed or offset image W. Landsman Mar 1996 Proper rounding of zoomed pixel values W. Landsman/R. Hurt Dec. 1997 Remove unneeded calls to obsolete !ERR W. Landsman December 2000 Replace remaining !ERR calls with !MOUSE.BUTTON W. Landsman Jan 2001 Allow for non-celestial (e.g. Galactic) coordinates W. Landsman Apr 2003 Work if RA/Dec reversed in CTYPE keyword W. Landsman Feb. 2004 Always call UNZOOM_XY for MOUSSE compatibility W. Landsman Sep. 2004 Added ALT keyword W. Landsman October 2004 Always test if offset/zoom supplied W. Landsman Feb 2008
(See $IDLUTILS_DIR/goddard/pro/tv/curval.pro)
DAOERF
NAME: DAOERF PURPOSE: Calulates the intensity, and derivatives, of a 2-d Gaussian PSF EXPLANATION: Corrects for the finite size of a pixel by integrating the Gaussian over the size of the pixel. Used in the IDL-DAOPHOT sequence. CALLING SEQUENCE: DAOERF, XIN, YIN, A, F, [ PDER ] INPUTS: XIN - input scalar, vector or array, giving X coordinate values YIN - input scalar, vector or array, giving Y coordinate values, must have same number of elements as XIN. A - 5 element parameter array describing the Gaussian A(0) - peak intensity A(1) - X position of peak intensity (centroid) A(2) - Y position of peak intensity (centroid) A(3) - X sigma of the gaussian (=FWHM/2.345) A(4) - Y sigma of gaussian OUTPUTS: F - array containing value of the function at each (XIN,YIN) The number of output elements in F and PDER is identical with the number of elements in X and Y OPTIONAL OUTPUTS: PDER - 2 dimensional array of size (NPTS,5) giving the analytic derivative at each value of F with respect to each parameter A. REVISION HISTORY: Written: W. Landsman October, 1987 Converted to IDL V5.0 W. Landsman September 1997
(See $IDLUTILS_DIR/goddard/pro/idlphot/daoerf.pro)
DAO_VALUE
NAME: DAO_VALUE PURPOSE: Returns the value of a DAOPHOT point-spread function at a set of points. EXPLANATION: The value of the point-spread function is the sum of a two-dimensional integral under a bivariate Gaussian function, and a value obtained by interpolation in a look-up table. DAO_VALUE will optionally compute the derivatives wrt X and Y CALLING SEQUENCE: Result = DAO_VALUE( xx, yy, gauss, psf, [ dvdx, dvdy ] ) INPUTS: XX,YY - the real coordinates of the desired point relative to the centroid of the point-spread function. GAUSS - 5 element vector describing the bivariate Gaussian GAUSS(0)- the peak height of the best-fitting Gaussian profile. GAUSS(1,2) - x and y offsets from the centroid of the point-spread function to the center of the best-fitting Gaussian. GAUSS(3,4) - the x and y sigmas of the best-fitting Gaussian. PSF - a NPSF by NPSF array containing the look-up table. OUTPUTS: RESULT - the computed value of the point-spread function at a position XX, YY relative to its centroid (which coincides with the center of the central pixel of the look-up table). OPTIONAL OUTPUTS: DVDX,DVDY - the first derivatives of the composite point-spread function with respect to x and y. NOTES although the arguments XX,YY of the function DAO_VALUE are relative to the centroid of the PSF, the function RINTER which DAO_VALUE calls requires coordinates relative to the corner of the array (see code). PROCEDURES CALLED: DAOERF, RINTER() REVISON HISTORY: Adapted to IDL by B. Pfarr, STX, 11/17/87 from 1986 STSDAS version of DAOPHOT Converted to IDL V5.0 W. Landsman September 1997
(See $IDLUTILS_DIR/goddard/pro/idlphot/dao_value.pro)
DATE
NAME: DATE PURPOSE: Convert day-of-year to a DD-MMM-YYYY string CALLING SEQUENCE: D_String = DATE(Year, day ) INPUTS: Year - Integer scalar specifying the year. If the year contains only two digits, then it is assumed to indicate the number of years after 1900. Day - Integer scalar giving number of days after Jan 0 of the specified year. Can be larger than 366 OUTPUTS: D_String - String giving date in format '13-MAR-1986' RESTRICTIONS: Will not work for years before 100 AD EXAMPLE: IDL> print, date(1997,279) '6-Oct-1997' MODIFICATION HISTORY: D.M. fecit 24 October,1983 Work for years outside of the 19th century W. Landsman September 1997 Converted to IDL V5.0 W. Landsman September 1997
(See $IDLUTILS_DIR/goddard/pro/astro/date.pro)
DATE_CONV
NAME: DATE_CONV PURPOSE: Procedure to perform conversion of dates to one of three possible formats. EXPLANATION: The following date formats are allowed format 1: real*8 scalar encoded as: year*1000 + day + hour/24. + min/24./60 + sec/24./60/60 where day is the day of year (1 to 366) format 2: Vector encoded as: date[0] = year (eg. 2005) date[1] = day of year (1 to 366) date[2] = hour date[3] = minute date[4] = second format 3: string (ascii text) encoded as DD-MON-YEAR HH:MM:SS.SS (eg. 14-JUL-2005 15:25:44.23) OR YYYY-MM-DD HH:MM:SS.SS (ISO standard) (eg. 1987-07-14 15:25:44.23 or 1987-07-14T15:25:44.23) format 4: three element vector giving spacecraft time words from a Hubble Space Telescope (HST) telemetry packet. Based on total number of secs since midnight, JAN. 1, 1979 format 5: Julian day. As this is also a scalar, like format 1, the distinction between the two on input is made based on their value. Numbers > 2300000 are interpreted as Julian days. CALLING SEQUENCE results = DATE_CONV( DATE, TYPE ) INPUTS: DATE - input date in one of the possible formats. Must be scalar. TYPE - type of output format desired. If not supplied then format 3 (real*8 scalar) is used. valid values: 'REAL' - format 1 'VECTOR' - format 2 'STRING' - format 3 'FITS' - YYYY-MM-DDTHH:MM:SS.SS' 'JULIAN' - Julian date 'MODIFIED' - Modified Julian date (JD-2400000.5) TYPE can be abbreviated to the single character strings 'R', 'V', 'S', 'F', 'J', and 'M'. Nobody wants to convert TO spacecraft time (I hope!) OUTPUTS: The converted date is returned as the function value. EXAMPLES: IDL> print,date_conv('2006-03-13 19:58:00.00'),f='(f15.5)' 2006072.83194 IDL> print,date_conv( 2006072.8319444d,'F') 2006-03-13T19:58:00.00 IDL> print,date_conv( 2006072.8319444d,'V') 2006.00 72.0000 19.0000 57.0000 59.9962 IDL> print,date_conv( 2006072.8319444d,'J'), f='(f15.5)' 2453808.33194 HISTORY: version 1 D. Lindler July, 1987 adapted for IDL version 2 J. Isensee May, 1990 Made year 2000 compliant; allow ISO format input jls/acc Oct 1998 DJL/ACC Jan 1998, Modified to work with dates such as 6-JAN-1996 where day of month has only one digit. DJL, Nov. 2000, Added input/output format YYYY-MM-DDTHH:MM:SS.SS Replace spaces with '0' in output FITS format W.Landsman April 2006 Added Julian date capabilities on input and output. M.Perrin, July 2007 Removed spurious /WARN keyword to MESSAGE W.L. Feb 2012
(See $IDLUTILS_DIR/goddard/pro/astro/date_conv.pro)
DAYCNV
NAME: DAYCNV PURPOSE: Converts Julian dates to Gregorian calendar dates CALLING SEQUENCE: DAYCNV, XJD, YR, MN, DAY, HR INPUTS: XJD = Julian date, positive double precision scalar or vector OUTPUTS: YR = Year (Integer) MN = Month (Integer) DAY = Day (Integer) HR = Hours and fractional hours (Real). If XJD is a vector, then YR,MN,DAY and HR will be vectors of the same length. EXAMPLE: IDL> DAYCNV, 2440000.D, yr, mn, day, hr yields yr = 1968, mn =5, day = 23, hr =12. WARNING: Be sure that the Julian date is specified as double precision to maintain accuracy at the fractional hour level. METHOD: Uses the algorithm of Fliegel and Van Flandern (1968) as reported in the "Explanatory Supplement to the Astronomical Almanac" (1992), p. 604 Works for all Gregorian calendar dates with XJD > 0, i.e., dates after -4713 November 23. REVISION HISTORY: Converted to IDL from Yeoman's Comet Ephemeris Generator, B. Pfarr, STX, 6/16/88 Converted to IDL V5.0 W. Landsman September 1997
(See $IDLUTILS_DIR/goddard/pro/astro/daycnv.pro)
DBBUILD
NAME: DBBUILD PURPOSE: Build a database by appending new values for every item. EXPLANATION: The database must be opened for update (with DBOPEN) before calling DBBUILD. This version for IDL V6.1 or later. CALLING SEQUENCE: DBBUILD, [ v1, v2, v3, v4......v50, /NOINDEX, /SILENT, STATUS = ] INPUTS: v1,v2....v50 - vectors containing values for all items in the database. V1 contains values for the first item, V2 for the second, etc. The number of vectors supplied must equal the number of items (excluding entry number) in the database. The number of elements in each vector should be the same. A multiple valued item should be dimensioned NVALUE by NENTRY, where NVALUE is the number of values, and NENTRY is the number of entries. OPTIONAL INPUT KEYWORDS: /NOINDEX - If this keyword is supplied and non-zero then DBBUILD will *not* create an indexed file. Useful to save time if DBBUILD is to be called several times and the indexed file need only be created on the last call /SILENT - If the keyword SILENT is set and non-zero, then DBBUILD will not print a message when the index files are generated OPTIONAL OUTPUT KEYWORD: STATUS - Returns a status code denoting whether the operation was successful (1) or unsuccessful (0). Useful when DBBUILD is called from within other applications. EXAMPLE: Suppose a database named STARS contains the four items NAME,RA,DEC, and FLUX. Assume that one already has the four vectors containing the values, and that the database definition (.DBD) file already exists. IDL> !PRIV=2 ;Writing to database requires !PRIV=2 IDL> dbcreate,'stars',1,1 ;Create database (.DBF) & index (.DBX) file IDL> dbopen,'stars',1 ;Open database for update IDL> dbbuild,name,ra,dec,flux ;Write 4 vectors into the database NOTES: Do not call DBCREATE before DBBUILD if you want to append entries to an existing database DBBUILD checks that each value vector matches the idl type given in the database definition (..dbd) file, and that character strings are the proper length. PROCEDURE CALLS: DBCLOSE, DBINDEX, DBXPUT, DBWRT, IS_IEEE_BIG() REVISION HISTORY: Written W. Landsman March, 1989 Added /NOINDEX keyword W. Landsman November, 1992 User no longer need supply all items W. Landsman December, 1992 Added STATUS keyword, William Thompson, GSFC, 1 April 1994 Added /SILENT keyword, William Thompson, GSFC, October 1995 Allow up to 30 items, fix problem if first item was multiple value W. Landsman GSFC, July 1996 Faster build of external databases on big endian machines W. Landsman GSFC, November 1997 Use SIZE(/TNAME) for error mesage display W.Landsman July 2001 Fix message display error introduced July 2001 W. Landsman Oct. 2001 Make sure error message appears even if !QUIET is set W.L November 2006 Major rewrite to use SCOPE_VARFETCH, accept 50 input items W. Landsman November 2006 Fix warning if parameters have different # of elements W.L. May 2010 Fix warning if scalar parameter supplied W.L. June 2010 Fix for when first parameter is multi-dimensioned W.L. July 2010 Check data type of first parameter W.L. Jan 2012
(See $IDLUTILS_DIR/goddard/pro/database/dbbuild.pro)
DBCIRCLE
NAME: DBCIRCLE PURPOSE: Find sources in a database within specified radius of specified center EXPLANATION: Database must include items named 'RA' (in hours) and 'DEC' (in degrees) and must have previously been opened with DBOPEN CALLING SEQUENCE: list = DBCIRCLE( ra_cen, dec_cen, [radius, dis, sublist, /SILENT, /GALACTIC, TO_B1950, /TO_J2000, COUNT= ] ) INPUTS: RA_CEN - Right ascension of the search center in decimal HOURS, scalar DEC_CEN - Declination of the search center in decimal DEGREES, scalar RA_CEN and DEC_CEN should be in the same equinox as the currently opened catalog. OPTIONAL INPUT: RADIUS - Radius of the search field in arc minutes, scalar. DBCIRCLE prompts for RADIUS if not supplied. SUBLIST - Vector giving entry numbers in currently opened database to be searched. Default is to search all entries OUTPUTS: LIST - Vector giving entry numbers in the currently opened catalog which have positions within the specified search circle LIST is set to -1 if no sources fall within the search circle OPTIONAL OUTPUT DIS - The distance in arcminutes of each entry specified by LIST to the search center (given by RA_CEN and DEC_CEN) OPTIONAL KEYWORD INPUT: /GALACTIC - if set, then the first two parameters are interpreted as Galactic coordinates in degrees, and is converted internally to J2000 celestial to search the database. /SILENT - If this keyword is set, then DBCIRCLE will not print the number of entries found at the terminal /TO_J2000 - If this keyword is set, then the entered coordinates are assumed to be in equinox B1950, and will be converted to J2000 before searching the database /TO_B1950 - If this keyword is set, then the entered coordinates are assumed to be in equinox J2000, and will be converted to B1950 before searching the database NOTE: The user must determine on his own whether the database is in B1950 or J2000 coordinates. OPTIONAL KEYWORD OUTPUT: COUNT - - Integer scalar giving the number of valid matches METHOD: A DBFIND search is first performed on a square area of given radius. The list is the restricted to a circular area by using GCIRC to compute the distance of each object to the field center. RESTRICTIONS; The database must have items 'RA' (in hours) and 'DEC' (in degrees). Alternatively, the database could have items RA_OBJ and DEC_OBJ (both in degrees) EXAMPLE: Find all Hipparcos stars within 40' of the nucleus of M33 (at J2000 1h 33m 50.9s 30d 39' 36.7'') IDL> dbopen,'hipparcos' IDL> list = dbcircle( ten(1,33,50.9), ten(3,39,36.7), 40) PROCEDURE CALLS: BPRECESS, DBFIND(), DBEXT, DB_INFO(), GCIRC, GLACTC, JPRECESS REVISION HISTORY: Written W. Landsman STX January 1990 Fixed search when crossing 0h July 1990 Spiffed up code a bit October, 1991 Leave DIS vector unchanged if no entries found W. Landsman July 1999 Use maximum declination, rather than declination at field center to correct RA for latitude effect W. Landsman September 1999 Added COUNT, GALACTIC keywords W. Landsman December 2008 Fix problem when RA range exceeds 24h W. Landsman April 2009 Work as advertised for RA_OBJ field W. Landsman June 2010
(See $IDLUTILS_DIR/goddard/pro/database/dbcircle.pro)
DBCLOSE
NAME: DBCLOSE PURPOSE: procedure to close a data base file CALLING SEQUENCE: dbclose INPUTS: None OUTPUTS None SIDE EFFECTS: the data base files currently opened are closed PROCEDURE CALLS: DB_INFO(), HOST_TO_IEEE HISTORY: version 2 D. Lindler Oct. 1987 For IDL version 2 August 1990 William Thompson, GSFC/CDS (ARC), 30 May 1994 Added support for external (IEEE) data format Converted to IDL V5.0 W. Landsman September 1997
(See $IDLUTILS_DIR/goddard/pro/database/dbclose.pro)
DBCOMPARE
NAME: DBCOMPARE PURPOSE: Display two entries in an IDL database side by side in a column format CALLING SEQUENCE: dbcompare, list1, list2, [items, TEXTOUT= , /DIFF] INPUTS: list1 - Integer scalar giving first entry number to be compared. list2 - Integer scalar giving second entry number to be compared. OPTIONAL INPUT-OUTPUT: items - items to be compared, if not supplied then all items will be compared. The items can be specified in any of the following ways: form 1 scalar string giving item(s) as list of names separated by commas form 2 string array giving list of item names form 3 string of form '$filename' giving name of text file containing items (one item per line) line) form 4 integer scalar giving single item number or integer vector list of item numbers form 5 Null string specifying interactive selection. This is the default if 'items' is not supplied form 6 '*' select all items (= default) If items was undefined or a null string on input, then on output it will contain the items interactively selected. OPTIONAL INPUT KEYWORDS: /DIFF - If this keyword is set and non-zero, then only the items in the database that differ will be printed TEXTOUT - Scalar Integer (1-7) Used to determine output device. See TEXTOPEN for more info. SYSTEM VARIABLES: Output device controlled by non-standard system variable !TEXTOUT, if TEXTOUT keyword is not used. EXAMPLE: Display entries 3624 and 3625 in column form showing only the items that differ. IDL> dbcompare,3624,3625,/diff PROCEDURES USED: DB_INFO(), DB_ITEM, DB_ITEM_INFO(), DBRD, DBXVAL() TEXTOPEN, TEXTCLOSE HISTORY: Written, W. Landsman July 1996 Fix documentation, add Syntax display W. Landsman November 1998 Replace DATATYPE() with size(/TNAME) W. Landsman November 2001 Assume since V5.5, remove VMS call W. Landsman September 2006 Fix problem with multiple values when /DIFF set W. Landsman April 2007
(See $IDLUTILS_DIR/goddard/pro/database/dbcompare.pro)
DBCREATE
NAME: DBCREATE PURPOSE: Create a new data base (.dbf), index (.dbx) or description (.dbh) file EXPLANATION: A database definition (.dbd) file must already exist in the current directory or in a ZDBASE directory. The new .dbf, .dbx and/or .dbh files will be written to the same directory. So if the .dbd file is in a ZDBASE directory, then the user must have write privilege to that directory This version allows record length to be larger than 32767 bytes CALLING SEQUENCE: dbcreate, name,[ newindex, newdb, maxitems] [,/EXTERNAL, MAXENTRY=] INPUTS: name- name of the data base (with no qualifier), scalar string. The description will be read from the file "NAME".dbd Maximum length of name is 19 characters. OPTIONAL INPUTS: newindex - if non-zero then a new index file is created, otherwise it is assumed that changes do not affect the index file. (default=0) newdb - if non-zero then a new data base file (.dbf) will be created. Otherwise changes are assumed not to affect the file's present format. maxitems - maximum number of items in data base. If not supplied then the number of items is limited to 200. OUTPUTS: NONE. OPTIONAL INPUT KEYWORDS: external - If set, then the database is written with an external data representation. This allows the database files to be used on any computer platform, e.g. through NFS mounts, but some overhead is added to reading the files. The default is to write the data in the native format of the computer being used. This keyword is only paid attention to if NEWDB or NEWINDEX are nonzero. Otherwise, the database is opened to find out if it uses external representation or not. Extreme caution should be used if this keyword is used with only NEWINDEX set to a nonzero value. This mode is allowed so that databases written on machines which already use the external data representation format, e.g. Sun workstations, to be marked external so that other machines can read them. MAXENTRY - positive integer giving the maximum number of entries in the database (needed to adjust the size of the index file). This keyword can be used to supercede the #maxentries line in the .dbd file (the larger of the two numbers will be used). PROCEDURE CALLS: GETTOK(), FIND_WITH_DEF(), ZPARCHECK RESTRICTIONS: If newdb=0 is not specified, the changes to the .dbd file can not alter the length of the records in the data base file. and may not alter positions of current fields in the file. permissible changes are: 1) utilization of spares to create a item or field 2) change in field name(s) 3) respecification of index items 4) changes in default print formats 5) change in data base title 6) changes in pointer specification to other data data bases !priv must be 2 or greater to execute this routine. SIDE EFFECTS: data base description file ZDBASE:name.dbh is created and optionally ZDBASE:name.dbf (data file) and ZDBASE.dbx (index file) if it is a new data base. REVISION HISTORY: D. Lindler, GSFC/HRS, October 1987 Modified: Version 1, William Thompson, GSFC, 29 March 1994 Version 2, William Thompson, GSFC/CDS (ARC), 28 May 1994 Added EXTERNAL keyword. Version 4, William Thompson, GSFC, 3 November 1994 Modified to allow ZDBASE to be a path string. 8/14/95 JKF/ACC - allow EXTERNAL data for newindex OR newdb modes. Make sure all databases closed before starting W. Landsman June 1997 Added new unsigned and 64 bit integer datatypes W. Landsman July 2001 Make sure to use lowercase filenames on Unix W. Landsman May 2006 Added MAXENTRY keyword W. Landsman July 2006 Assume since V5.5, remove obsolete keywords to OPEN W. Landsman Sep2006 No longer required to be a ZDBASE directory W. Landsman Feb 2008 Fix Feb 2008 bug when files are in current dir W. L. May 2008 Fix May 2008 bug when files are not in current dir (sigh) W. L. May 2008 Warn if database length exceeds 32767 bytes W.L. Dec 2009 Remove spurious warning that database name is too long W.L. April 2010 Support entry lengths larger than 32767 bytes W.L. Oct. 2010 Better testing for valid print formats W.L. Nov 2010
(See $IDLUTILS_DIR/goddard/pro/database/dbcreate.pro)
DBDELETE
NAME: DBDELETE PURPOSE: Deletes specified entries from data base CALLING SEQUENCE: DBDELETE, list, [ name, /DEBUG ] INPUTS: list - list of entries to be deleted, scalar or vector name - optional name of data base, scalar string. If not specified then the data base file must be previously opened for update by DBOPEN. OPERATIONAL NOTES: !PRIV must be at least 3 to execute. SIDE EFFECTS: The data base file (ZDBASE:name.dbf) is modified by removing the specified entries and reordering the remaining entry numbers accordingly (ie. if you delete entry 100, it will be replaced by entry 101 and the database will contain 1 less entry. EXAMPLE: Delete entries in a database STARS where RA=DEC = 0.0 IDL> !PRIV= 3 ;Set privileges IDL> dbopen,'STARS',1 ;Open for update IDL> list = dbfind('ra=0.0,dec=0.0') ;Obtain LIST vector IDL> dbdelete, list ;Delete specified entries from db NOTES: The procedure is rather slow because the entire database is re- created with the specified entries deleted. OPTIONAL KEYWORD INPUT: DEBUG - if this keyword is set and non-zero, then additional diagnostics will be printed as each entry is deleted. COMMON BLOCKS: DBCOM PROCEDURE CALLS: DBINDEX, DB_INFO(), DBOPEN, DBPUT, ZPARCHECK HISTORY Version 2 D. Lindler July, 1989 Updated documentation W. Landsman December 1992 William Thompson, GSFC, 28 February 1995 Fixed bug when external representation used. Fixed for case where second parameter supplied W. Landsman April 1996 Use keyword DEBUG rather than !DEBUG W. Landsman May 1997 Don't call DBINDEX if no indexed items W. Landsman May 2006 Use TRUNCATE_LUN if V5.6 or later W. Landsman Sep 2006 Fix problem when deleting last entry W. Landsman Mar 2007 Assume since V5.6 so TRUNCATE_LUN is available W. Landsman
(See $IDLUTILS_DIR/goddard/pro/database/dbdelete.pro)
DBEDIT
NAME: DBEDIT PURPOSE: Interactively edit specified fields in an IDL database. EXPLANATION: The value of each field is displayed, and the user has the option of changing or keeping the value. Widgets will be used if they are available. CALLING SEQUENCE: dbedit, list, [ items ] INPUTS: list - scalar or vector of database entry numbers. Set list = 0 to interactively add a new entry to a database. Set list = -1 to edit all entries. OPTIONAL INPUTS: items - list of items to be edited. If omitted, all fields can be edited. KEYWORDS: BYTENUM = If set, treat byte variables as numbers instead of characters. COMMON BLOCKS: DB_COM -- contains information about the opened database. DBW_C -- contains information intrinsic to this program. SIDE EFFECTS: Will update the database files. RESTRICTIIONS: Database must be opened for update prior to running this program. User must be running DBEDIT from an account that has write privileges to the databases. If one is editing an indexed item, then after all edits are complete, DBINDEX will be called to reindex the entire item. This may be time consuming. Cannot be used to edit items with multiple values EXAMPLE: Suppose one had new parallaxes for all stars fainter than 5th magnitude in the Yale Bright Star Catalog and wanted to update the PRLAX and PRLAX_CODE fields with these new numbers IDL> !priv=2 IDL> dbopen, 'yale_bs', 1 ;Open catalog for update IDL> list = dbfind( 'v>5') ;Find fainter than 5th magnitude IDL> dbedit, list, 'prlax, prlax_code' ;Manual entry of new values PROCEDURE: (1) Use the cursor and point to the value you want to edit. (2) Type the new field value over the old field value. (3) When you are done changing all of the field values for each entry save the entry to the databases by pressing 'SAVE ENTRY TO DATABASES'. Here all of the values will be checked to see if they are the correct data type. If a field value is not of the correct data type, it will not be saved. Use the buttons "PREV ENTRY" and "NEXT ENTRY" to move between entry numbers. You must save each entry before going on to another entry in order for your changes to be saved. Pressing "RESET THIS ENTRY" will remove any unsaved changes to the current entry. REVISION HISTORY: Adapted from Landsman's DBEDIT added widgets, Melissa Marsh, HSTX, August 1993 do not need to press return after entering each entry, fixed layout problem on SUN, Melissa Marsh, HSTX, January 1994 Only updates the fields which are changed. Joel Offenberg, HSTX, Mar 94 Corrected test for changed fields Wayne Landsman HSTX, Mar 94 Removed a couple of redundant statements W. Landsman HSTX Jan 96 Converted to IDL V5.0 W. Landsman September 1997 Replace DATAYPE() with size(/TNAME) W. Landsman November 2001 Work for entry numbers > 32767 W. Landsman December 2001 Added /BYTENUM William Thompson 13-Mar-2006 Use DIALOG_MESSAGE for error messages W. Landsman April 2006 Assume since V5.5, remove VMS support W. Landsman Sep 2006
(See $IDLUTILS_DIR/goddard/pro/database/dbedit.pro)
DBEDIT_BASIC
NAME: DBEDIT_BASIC PURPOSE: Subroutine of DBEDIT_BASIC to edit a database on a dumb terminal. EXPLANATION: Interactively edit specified fields in a database. The value of each field is displayed, and the user has the option of changing or keeping the value. CALLING SEQUENCE: dbedit_basic, list, [ items ] INPUTS: list - scalar or vector of database entry numbers. Set LIST=0 to interactively add a new entry to a database. OPTIONAL INPUTS items - list of items to be edited. If not supplied, then the value of every field will be displayed. NOTES: (1) Database must be opened for update (dbopen,<dbname>,1) before calling DBEDIT_BASIC. User must have write privileges on the database files. (2) User gets a second chance to look at edited values, before they are actually written to the database PROMPTS: The item values for each entry to be edited are first displayed User is the asked "EDIT VALUES IN THIS ENTRY (Y(es), N(o), or Q(uit))? If user answers 'Y' or hits RETURN, then each item is displayed with its current value, which the user can update. If user answered 'N' then DBEDIT_BASIC skips to the next entry. If user answers 'Q' then DBEDIT will exit, saving all previous changes. EXAMPLE: Suppose V magnitudes (V_MAG) in a database STARS with unknown values were assigned a value of 99.9. Once the true values become known, the database can be edited IDL> !PRIV=2 & dbopen,'STARS',1 ;Open database for update IDL> list = dbfind('V_MAG=99.9') ;Get list of bad V_MAG values IDL> dbedit,list,'V_MAG' ;Interactively insert good V_MAG values REVISION HISTORY: Written W. Landsman STX April, 1989 Rename DBEDIT_BASIC from DBEDIT July, 1993 Converted to IDL V5.0 W. Landsman September 1997 Change DATATYPE() to size(/TNAME) W. Landsman November 2001
(See $IDLUTILS_DIR/goddard/pro/database/dbedit_basic.pro)
DBEXT
NAME: DBEXT PURPOSE: Extract values of up to 12 items from an IDL database EXPLANATION: Procedure to extract values of up to 12 items from data base file, and place into IDL variables CALLING SEQUENCE: dbext,list,items,v1,[v2,v3,v4,v5,v6,v7,v8,v9,v10,v11,v12] INPUTS: list - list of entry numbers to be printed, vector or scalar If list = -1, then all entries will be extracted. list may be converted to a vector by DBEXT items - standard item list specification. See DBPRINT for the 6 different ways that items may be specified. OUTPUTS: v1...v12 - the vectors of values for up to 12 items. EXAMPLE: Extract all RA and DEC values from the currently opened database, and place into the IDL vectors, IDLRA and IDLDEC. IDL> DBEXT,-1,'RA,DEC',idlra,idldec HISTORY version 2 D. Lindler NOV. 1987 check for INDEXED items W. Landsman Feb. 1989 Converted to IDL V5.0 W. Landsman September 1997 Avoid EXECUTE() call for V6.1 or later W. Landsman December 2006 Assume since V6.1 W. Landsman June 2009
(See $IDLUTILS_DIR/goddard/pro/database/dbext.pro)
DBEXT_DBF
NAME: DBEXT_DBF PURPOSE: Subroutine of DBEXT to extract values of up to 18 items from a database EXPLANATION: This is a subroutine of DBEXT, which is the routine a user should normally use. CALLING SEQUENCE: dbext_dbf,list,dbno,sbyte,nbytes,idltype,nval,v1,[ v2,v3,v4,v5,v6,v7, v8,v9,v10,v11,v12,v13,v14,v15,v16,v17,v18 ITEM_DBNO = ] INPUTS: list - list of entry numbers to extract desired items. It is the entry numbers in the primary data base unless dbno is greater than or equal to -1. In that case it is the entry number in the specified data base. dbno - number of the opened db file if set to -1 then all data bases are included sbyte - starting byte in the entry. If single data base then it must be the starting byte for that data base only and not the concatenation of db records nbytes - number of bytes in the entry idltype - idl data type of each item to be extracted nval - number of values per entry of each item to be extracted OUTPUTS: v1...v18 - the vectors of values for up to 18 items OPTIONAL INPUT KEYWORD: item_dbno - A vector of the individual database numbers for each item. Simplifies the code for linked databases PROCEDURE CALLS: DB_INFO(), DB_ITEM_INFO(), DBRD, DBXVAL(), IS_IEEE_BIG(), IEEE_TO_HOST HISTORY version 1 D. Lindler Nov. 1987 Extract multiple valued entries W. Landsman May 1989 William Thompson, GSFC/CDS (ARC), 1 June 1994 Added support for external (IEEE) representation. Work with multiple element string items W. Landsman August 1995 Increase speed for external databases on IEEE machines WBL August 1996 IEEE conversion implemented on blocks of entries using BIG Added keyword ITEM_DBNO R. Schwartz, GSFC/SDAC, August 1996 Return a vector even if only 1 value W. Thompson October 1996 Change variable name of BYTESWAP to BSWAP W. Thompson Mar 1997 Use /OVERWRITE with reform W. Landsman May 1997 Increase maximum number of items to 18 W. Landsman November 1999 2 May 2003, W. Thompson, Use DBXVAL with BSWAP instead of IEEE_TO_HOST. Avoid EXECUTE() for V6.1 or later W. Landsman Jan 2007 Assume since V6.1 W. Landsman June 2009 Change arrays to LONG to support entries >32767 bytes WL Oct 2010
(See $IDLUTILS_DIR/goddard/pro/database/dbext_dbf.pro)
DBEXT_IND
NAME: DBEXT_IND PURPOSE: routine to read a indexed item values from index file CALLING SEQUENCE: dbext_ind,list,item,dbno,values INPUTS: list - list of entry numbers to extract values for (if it is a scalar, values for all entries are extracted) item - item to extract dbno - number of the opened data base OUTPUT: values - vector of values returned as function value HISTORY: version 1 D. Lindler Feb 88 Faster processing of string values W. Landsman April, 1992 William Thompson, GSFC/CDS (ARC), 30 May 1994 Added support for external (IEEE) data format Allow multiple valued (nonstring) index items W. Landsman November 2000 Use 64bit integer index for large databases W. Landsman February 2001 Fix sublisting of multiple valued index items W. Landsman March 2001 Check whether any supplied entries are valid W. Landsman Jan 2009
(See $IDLUTILS_DIR/goddard/pro/database/dbext_ind.pro)
DBFIND()
NAME: DBFIND() PURPOSE: Search data base for entries with specified characteristics EXPLANATION: Function to search data base for entries with specified search characteristics. CALLING SEQUENCE: result = dbfind(spar,[ listin, /SILENT, /FULLSTRING, ERRMSG=, Count = ]) INPUTS: spar - search_parameters (string)...each search parameter is of the form: option 1) min_val < item_name < max_val option 2) item_name = value option 3) item_name = [value_1, value_10] Note: option 3 is also the slowest. option 4) item_name > value option 5) item_name < value option 6) item_name = value(tolerance) ;eg. temp=25.0(5.2) option 7) item_name ;must be non-zero Multiple search parameters are separated by a comma. eg. 'cam_no=2,14<ra<20' Note: < is interpreted as less than or equal. > is interpreted as greater than or equal. RA and DEC keyfields are stored as floating point numbers in the data base may be entered as HH:MM:SEC and DEG:MIN:SEC. Where: HH:MM:SEC equals HH + MM/60.0 + SEC/3600. DEG:MIN:SEC equals DEG + MIN/60.0 + SEC/3600. For example: 40:34:10.5 < dec < 43:25:19 , 8:22:1.0 < ra < 8:23:23.0 Specially encoded date/time in the data base may be entered by CCYY/DAY:hr:min:sec which is interpreted as CCYY*1000+DAY+hr/24.0+min/24.0/60.+sec/24.0/3600. If a two digit year is supplied and YY GE 40 then it is understood to refer to year 1900 +YY; if YY LT 40 then it is understood to refer to year 2000 +YY For example 1985/201:10:35:30<date_time<1985/302:10:33:33.4 would specify all entries between: year 1985 day 201 at 10:35:30 to day 302 at 10:33:33.4 The date/time may also be encoded as: DD-MMM-YEAR HH::MM:SS.SS eg. 12-JUL-86 10:23:33.45 (this is the format of system variable !stime) Multiple search parameters may be stored in a string array (one parameter per array element) instead of concatenating them with commas in a single string. Example: input_array = strarr(2) input_array[0] = '14<ra<16' ; 14-16 hrs of ra. input_array[1] = '8<dec<20' ; + 8-20 deg. decl. OPTIONAL INPUT: listin - gives list of entries to be searched. If not supplied or set to -1 then all entries are searched. OUTPUT: List of ENTRY numbers satisfying search characteristics is returned as the function value. OPTIONAL INPUT KEYWORDS: /SILENT - If the keyword SILENT is set and non-zero, then DBFIND will not print the number of entries found. /FULLSTRING - By default, one has a match if a search string is included in any part of a database value (substring match). But if /FULLSTRING is set, then all characters in the database value must match the search string (excluding leading and trailing blanks). Both types of string searches are case insensitive. ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. In order to use this feature, ERRMSG must be defined first, e.g. ERRMSG = '' DB_ITEM, ERRMSG=ERRMSG, ... IF ERRMSG NE '' THEN ...; OPTIONAL OUTPUT KEYWORD: COUNT - Integer scalar giving the number of valid matches PROCEDURE CALLS: DB_INFO, DB_ITEM, DB_ITEM_INFO, DBEXT, DBEXT_IND, DBFIND_ENTRY, DBFIND_SORT, DBFPARSE, DBRD, DBSEARCH, ZPARCHECK,IS_IEEE_BIG RESTRICTIONS: The data base must be previously opened with DBOPEN. SIDE EFFECTS: The obsolete system variable !ERR is set to number of entries found REVISION HISTORY: Written : D. Lindler, GSFC/HRS, November 1987 Version 2, Wayne Landsman, GSFC/UIT (STX), 1 April 1994 Added FULLSTRING keyword. Version 3, William Thompson, GSFC, 1 April 1994 Added check for empty database Version 4, William Thompson, GSFC, 5 April 1994 Changed so that !ERR is zero when database is empty, and LISTIN is returned, based on discussion with Wayne Landsman. Version 5, Wayne Landsman, GSFC/UIT (STX), 26 May 1994 Added error message when database is empty. Version 6, William Thompson, GSFC, 14 March 1995 Added FULLSTRING keyword to DBFIND_SORT call Version 7, Richard Schwartz, GSFC/SDAC 23 August 1996 Move external to host conversion from DBRD to operation on extracted values only. Version 8, William Thompson, GSFC, 3 December 1996 Renamed BYTESWAP variable to BSWAP--appeared to be conflicting with function of same name. Version 9, William Thompson, GSFC, 17-Mar-1997 Added keyword ERRMSG Version 10, July, 1997 W. Landsman, added CATCH errors Converted to IDL V5.0 W. Landsman October 1997 Update documentation for new Y2K compliant DBFPARSE W. Landsman Nov 1998 Suppress empty database message with /SILENT, W. Landsman Jan 1999 Added COUNT keyword, deprecate !ERR W. Landsman March 2000 Added new unsigned & 64bit datatypes W. Landsman July 2001 Fix possible floating illegand operand error W. Landsman July 2009 Change arrays to LONG to support entries >32767 bytes W.L. Oct. 2010
(See $IDLUTILS_DIR/goddard/pro/database/dbfind.pro)
DBFIND_ENTRY
NAME: DBFIND_ENTRY PURPOSE: Subroutine of DBFIND to perform an entry number search EXPLANATION: This is a subroutine of dbfind and is not a standalone procedure It performs a entry number search. CALLING SEQUENCE: dbfind_entry, type, svals, nentries, values, [COUNT = ] INPUTS: type - type of search (output from dbfparse) svals - search values (output from dbfparse) values - array of values to search OUTPUT: good - indices of good values OPTIONAL OUTPUT KEYWORD: Count - integer scalar giving the number of valid matches SIDE EFFECTS" The obsolete system variable !err is set to number of good values REVISION HISTORY: D. Lindler July,1987 Fixed test for final entry number W. Landsman Sept. 95 Converted to IDL V5.0 W. Landsman September 1997 Added COUNT keyword, deprecate !ERR W. Landsman March 2000 Better checking of out of range values W. Landsman February 2002
(See $IDLUTILS_DIR/goddard/pro/database/dbfind_entry.pro)
DBFIND_SORT
NAME: DBFIND_SORT PURPOSE: Subroutine of DBFIND to perform a search using sorted values EXPLANATION: This is a subroutine of dbfind and is not a standalone procedure It is used to limit the search using sorted values CALLING SEQUENCE: dbfind_sort, it, type, svals, list, [/FULLSTRING, COUNT = ] INPUT: it - item number, scalar type - type of search (output from dbfparse) svals - search values (output from dbfparse) INPUT/OUTPUT: list - found entries OPTIONAL INPUT KEYWORD: /FULLSTRING - By default, one has a match if a search string is included in any part of a database value (substring match). But if /FULLSTRING is set, then all characters in the database value must match the search string (excluding leading and trailing blanks). Both types of string searches are case insensitive. OPTIONAL OUTPUT KEYWORD Count - Integer scalar giving the number of matches found SYSTEM VARIABLES: The obsolete system variable !err is set to number of good values !ERR = -2 for an invalid search PROCEDURES CALLED: DB_INFO(), DB_ITEM_INFO(), DBSEARCH() REVISION HISTORY: D. Lindler July,1987 William Thompson, GSFC/CDS (ARC), 30 May 1994 Added support for external (IEEE) data format William Thompson, GSFC, 14 March 1995 Added keyword FULLSTRING Minimize use of obsolete !ERR variable W. Landsman February 2000 Added COUNT keyword, deprecate !ERR W. Landsman March 2000 Use 64 bit integers V5.2 or later Include new IDL unsigned & 64 bit integer datatypes W.Landsman July 2001 Make sure returned list vector is LONG W. Landsman August 2001 Work on string items W. Landsman November 2009 Don't use VALUE_LOCATE on a single value W. Landsman November 2009 Use VALUE_LOCATE even for equal values W. Landsman December 2009 Fix bug allowing negative FIRST values, William Thompson, 10 May 2010
(See $IDLUTILS_DIR/goddard/pro/database/dbfind_sort.pro)
DBFPARSE
NAME: DBFPARSE PURPOSE: Parse the search string supplied to DBFIND. Not a standalone routine CALLING SEQUENCE: DBFPARSE, [ spar, items, stype, values ] INPUTS: spar - search parameter specification, scalar string OUTPUTS: items - list of items to search on stype - search type, numeric scalar 0 item=values(j,0) -1 item>values(j,0) -2 item<values(j,1) -3 values(j,0)<item<values(j,1) -4 item is non zero -5 item=values(j,0) within tolerance values(j,1) 0< items in list values(j,i) for i=0,stype-1 values - search values, 20 x 10 string array, can parse a string with up to 20 items specifications, each item can have 10 values REVISION HISTORY: D. Lindler NOV, 1987 Check for valid numeric values before assuming a date string W. Landsman July, 1993 Accept four digit years when in ccyy/doy format W. Landsman October 1998 Don't do DATE/Time test for string items W. Landsman July 2006
(See $IDLUTILS_DIR/goddard/pro/database/dbfparse.pro)
DBGET
NAME: DBGET PURPOSE: Find entry numbers which contain specified values of a given item. EXPLANATION: DBGET() is useful as an alternative to DBFIND() when the desired search values are not easily expressed as a string. CALLING SEQUENCE: list = dbget( item, values, [ listin ], /SILENT, /FULLSTRING ) INPUTS: item - Item name or number values - scalar or vector containing item values to search for. OPTIONAL INPUTS: listin - list of entries to be searched. If not supplied, or set to -1, then all entries are searched OUTPUT: list - vector giving the entry number of entries containing desired item values. The number of elements in LIST may be different from that of VALUE, since a value might be located zero, once, or many times in the database. Use the function DBMATCH if a one to one correspondence is desired between VALUES and LIST. OPTIONAL INPUT KEYWORDS: /SILENT - If this keyword is set, then DBGET will not display the number of entries found /FULLSTRING - By default, one has a match if a search string is included in any part of a database value (substring match). But if /FULLSTRING is set, then all characters in the database value must match the search string (excluding leading and trailing blanks). Both types of string searches are case insensitive. OPTIONAL OUTPUT KEYWORD: COUNT - Integer scalar giving the number of valid matches RESTRICTIONS: When linked databases are opened together, DBGET can only be used to search on items in the primary database. EXAMPLE: Get info on selected HD stars in Bright Star catalogue IDL> dbopen, 'YALE_BS' IDL> hdno = [1141,2363,3574,4128,6192,6314,6668] ;Desired HD numbers IDL> list = dbget( 'HD', hdno ) ;Get corresponding entry numbers SYSTEM VARIABLES: The obsolete system variable !ERR is set to number of entries found REVISION HISTORY: Written, W. Landsman STX February, 1989 William Thompson, GSFC, 14 March 1995 Added keyword FULLSTRING Converted to IDL V5.0 W. Landsman September 1997 Added COUNT keyword, deprecate !ERR W. Landsman March 2000 Fix bug introduced March 2000 W. Landsman November 2000 Fix possible bug when sublist supplied W. Landsman August 2008
(See $IDLUTILS_DIR/goddard/pro/database/dbget.pro)
DBHELP
NAME: DBHELP PURPOSE: List available databases or items in the currently open database EXPLANATION: Procedure to either list available databases (if no database is currently open) or the items in the currently open database. CALLING SEQUENCE: dbhelp, [ flag , TEXTOUT=, /SORT ] INPUT: flag - (optional) if set to nonzero then item or database descriptions are also printed default=0 If flag is a string, then it is interpreted as the name of a data base (if no data base is opened) or a name of an item in the opened data base. In this case, help is displayed only for the particular item or database OUTPUTS: None OPTIONAL INPUT KEYWORDS: TEXTOUT - Used to determine output device. If not present, the value of !TEXTOUT system variable is used (see TEXTOPEN ) 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 <program>.prt textout=4 laser.tmp textout=5 user must open file textout=7 same as 3 but text is appended to <program>.prt file if it already exists. textout = filename (default extension of .prt) /SORT - If set and non-zero, then the help items will be displayed sorted alphabetically. If more than one database is open, then this keyword does nothing. METHOD: If no data base is opened then a list of data bases are printed, otherwise the items in the open data base are printed. If a string is supplied for flag and a data base is opened flag is assumed to be an item name. The information for that item is printed along with contents in a optional file zdbase:dbname_itemname.hlp if a string is supplied for flag and no data base is opened, then string is assumed to be the name of a data base file. only information for that file is printed along with an optional file zdbase:dbname.hlp. PROCEDURES USED: DB_INFO(),DB_ITEM_INFO(),FIND_WITH_DEF(), TEXTOPEN, TEXTCLOSE, UNIQ() IDL VERSION: V5.3 or later (uses vectorized FDECOMP) HISTORY: Version 2 D. Lindler Nov 1987 (new db format) Faster printing of title desc. W. Landsman May 1989 Keyword textout added, J. Isensee, July, 1990 Modified to work on Unix, D. Neill, ACC, Feb 1991. William Thompson, GSFC/CDS (ARC), 1 June 1994 Added support for external (IEEE) representation. William Thompson, GSFC, 3 November 1994 Modified to allow ZDBASE to be a path string. Remove duplicate database names Wayne Landsman December 1994 8/17/95 jkf/acc - force lowercase filenames for .hlp files. Added /SORT keyword J. Sandoval/W. Landsman October 1998 V5.3 version use vectorized FDECOMP W. Landsman February 2001 Recognize 64 bit, unsigned integer datatypes W. Landsman September 2001 Fix display of number of bytes with /SORT W. Landsman February 2002 Assume since V5.2 W. Landsman February 2002 Assume since V5.5 W. Landsman
(See $IDLUTILS_DIR/goddard/pro/database/dbhelp.pro)
DBINDEX
NAME: DBINDEX PURPOSE: Procedure to create index file for data base CALLING SEQUENCE: dbindex, [ items ] OPTIONAL INPUT: items - names or numbers of items to be index -- if not supplied, then all indexed fields will be processed. OUTPUT: Index file <name>.dbx is created on disk location ZDBASE: OPERATIONAL NOTES: (1) Data base must have been previously opened for update by DBOPEN (2) Only 18 items can be indexed at one time. If the database has more than 18 items, then two separate calls to DBINDEX are needed. PROCEDURES CALLED: DBINDEX_BLK, DB_INFO(), DB_ITEM, DB_ITEM_INFO(), IEEE_TO_HOST, IS_IEEE_BIG() HISTORY: version 2 D. Lindler Nov 1987 (new db format) W. Landsman added optional items parameter Feb 1989 William Thompson, GSFC/CDS (ARC), 30 May 1994 Added support for external (IEEE) data format Test if machine is bigendian W. Landsman May, 1996 Change variable name of BYTESWAP to BSWAP W. Thompson Mar, 1997 Increased number of fields to 15 W. Landsman June, 1997 Increase number of items to 18 W. Landsman November 1999 Allow multiple valued (nonstring) index items W. Landsman November 2000 Use 64 bit integers for V5.2 or later W. Landsman February 2001 Do not use EXECUTE() for V6.1 or later, improve efficiency W. Landsman December 2006 Automatically enlarge .dbx file if needed, fix major bug in last update W. Landsman Dec 2006 Assume since V6.1 W. Landsman June 2009 Allow sorted string items W. Landsman October 2009
(See $IDLUTILS_DIR/goddard/pro/database/dbindex.pro)
DBINDEX_BLK
NAME: DBINDEX_BLK PURPOSE: Subroutine of DBINDEX to create associated variable of correct datatype EXPLANATION: DBINDEX_BLK will offset into the file by a specified amount in preparation for writing to the file. V5.2 or later CALLING SEQUENCE: res = dbindex_blk(unit, nb, bsz, ofb, dtype) INPUTS: unit The unit number assigned to the file. nb The number of blocks to offset into the file. bsz The size of each block, in bytes, to offset into the file. ofb The offset into the block, in bytes. dtype The IDL datatype as defined in the SIZE function OUTPUTS: res The returned variable. This is an associated variable. RESTRICTIONS: The file must have been previously opened. MODIFICATION HISTORY: Written by Michael R. Greason, STX, 14 June 1990. Converted to IDL V5.0 W. Landsman September 1997 Use 64 bit integer for very large databases W. Landsman February 2001 Added new unsigned & 64bit integer datatypes W. Landsman July 2001
(See $IDLUTILS_DIR/goddard/pro/database/dbindex_blk.pro)
DBMATCH
NAME: DBMATCH PURPOSE: Find the entry number in a database for each element of item values EXPLANATION: DBMATCH() is especially useful for finding a one-to-one correspondence between entries in different databases, and thus to create the vector needed for database pointers. CALLING SEQUENCE: list = DBMATCH( item, values, [ listin, /FULLSTRING ] ) INPUTS: ITEM - Item name or number, scalar VALUES - scalar or vector containing item values to search for. OPTIONAL INPUTS: LISTIN - list of entries to be searched. If not supplied, or set to -1, then all entries are searched OUTPUT: LIST - vector of entry numbers with the same number of elements as VALUES. Contains a value of 0 wherever the corresponding item value was not found. OPTIONAL INPUT: /FULLSTRING - By default, one has a match if a search string is included in any part of a database value (substring match). But if /FULLSTRING is set, then all characters in the database value must match the search string (excluding leading and trailing blanks). Both types of string searches are case insensitive. NOTES: DBMATCH is meant to be used for items which do not have duplicate values in a database (e.g. catalog numbers). If more than one entry is found for a particular item value, then only the first one is stored in LIST. When linked databases are opened together, DBMATCH can only be used to search on items in the primary database. EXAMPLE: Make a vector which points from entries in the Yale Bright Star catalog to those in the Hipparcos catalog, using the HD number IDL> dbopen, 'yale_bs' ;Open the Yale Bright star catalog IDL> dbext, -1, 'HD', hd ;Get the HD numbers IDL> dbopen, 'hipparcos' ;Open the Hipparcos catalog IDL> list = dbmatch( 'HD', HD) ;Get entries in Hipparcos catalog ;corresponding to each HD number. PROCEDURE CALLS: DB_ITEM, DB_ITEM_INFO(), DBEXT, DBFIND_SORT() REVISION HISTORY: Written, W. Landsman STX February, 1990 Fixed error when list in parameter used May, 1992 Faster algorithm with sorted item when listin parameter supplied Added keyword FULLSTRING,check for empty database, William Thompson, GSFC, 15 March 1995 Work for more than 32767 values, added CATCH W. Landsman July 1997 Change some loop variables to type LONG, W. Landsman July 1999 Remove loop for substring searches (faster) W. landsman August 1999 Replace DATATYPE() with size(/TNAME) W. Landsman November 2001 Fixed typo when search on sorted items W. Landsman February 2002 Fixed bug from Nov 2001 where /FULLSTRING was always set. W.L Feb 2007
(See $IDLUTILS_DIR/goddard/pro/database/dbmatch.pro)
DBOPEN
NAME: DBOPEN PURPOSE: Routine to open an IDL database CALLING SEQUENCE: dbopen, name, update INPUTS: name - (Optional) name or names of the data base files to open. It has one of the following forms: 'name' -open single data base file 'name1,name2,...,nameN' - open N files which are connected via pointers. 'name,*' -Open the data base with all data bases connected via pointers '' -Interactively allow selection of the data base files. If not supplied then '' is assumed. name may optionally be a string array with one name per element. update - (Optional) Integer flag specifing openning for update. 0 - Open for read only 1 - Open for update 2 - Open index file for update only !PRIV must be 2 or greater to open a file for update. If a file is opened for update only a single data base can be specified. OUTPUTS: none INPUT-OUTPUT KEYWORD: UNAVAIL - If present, a "database doesn't exit" flag is returned through it. 0 = the database exists and was opened (if no other errors arose). 1 = the database doesn't exist. Also if present, the error message for non-existent databases is suppressed. The action, however, remains the same. SIDE EFFECTS: The .DBF and .dbx files are opened using unit numbers obtained by GET_LUN. Descriptions of the files are placed in the common block DB_COM. PROCEDURES CALLED: DBCLOSE, DB_INFO(), SELECT_W, ZPARCHECK HISTORY: For IDL Version 2 W. Landsman May 1990 -- Will require further modfication once SCREEN_SELECT is working Modified to work under Unix, D. Neill, ACC, Feb 1991. UNAVAIL keyword added. M. Greason, Hughes STX, Feb 1993. William Thompson, GSFC/CDS (ARC), 1 June 1994 Added support for external (IEEE) representation. William Thompson, GSFC, 3 November 1994 Modified to allow ZDBASE to be a path string. 8/29/95 JKF/ACC - forces lowercase for input database names. W. Landsman, Use CATCH to catch errors July, 1997 W. Landsman Use vector call to FDECOMP, STRSPLIT() Sep 2006 W. Landsman Remove obsolete keywords to OPEN Sep 2006 Replace SCREEN_SELECT with SELECT_W, remove IEEE_TO_HOST WL Jan 2009 Fix typos in BYTEORDER introduced Jan 2009 G. Scandariato/W.L.Feb. 2009 Support new DB format which allows entry lengths > 32767 bytes W.L. October 2010 William Thompson, fixed bug opening multiple databases Dec 2010 Fix problem with external databases WL Sep 2011
(See $IDLUTILS_DIR/goddard/pro/database/dbopen.pro)
DBPRINT
NAME: DBPRINT PURPOSE: Procedure to print specified items from a list of database entries CALLING SEQUENCE: dbprint, list, [items, FORMS= , TEXTOUT= , /AdjustFormat, /NoHeader] INPUTS: list - list of entry numbers to be printed, vector or scalar if list = -1, then all entries will be printed. An error message is returned if any entry number is larger than the number of entries in the database OPTIONAL INPUT-OUTPUT: items - items to be printed, specified in any of the following ways: form 1 scalar string giving item(s) as list of names separated by commas form 2 string array giving list of item names form 3 string of form '$filename' giving name of text file containing items (one item per line) form 4 integer scalar giving single item number or integer vector list of item numbers form 5 Null string specifying interactive selection. This is the default if 'items' is not supplied form 6 '*' select all items, printout will be in table format. If items was undefined or a null string on input, then on output it will contain the items interactively selected. OPTIONAL INPUT KEYWORDS: /ADJUSTFORMAT - If set, then the format length for string items will be adjusted to the maximum length for the entries to be printed. This option will slow down DBPRINT because it requires the string items be extracted and their maximum length determined prior to any printing. However, it enables the display of string items without any truncation or wasted space. FORMS - The number of printed lines per page. If forms is not present, output assumed to be in PORTRAIT form, and a heading and 47 lines are printed on each page, with a page eject between each page. For LANDSCAPE form with headings on each page, and a page eject between pages, set forms = 34. For a heading only on the first page, and no page eject, set forms = 0. This is the default for output to the terminal. TEXTOUT - Integer (0-7) or string used to determine output device (see TEXTOPEN for more info). If not present, the !TEXTOUT system variable is used. 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 dbprint.prt (file) textout=4 laser.tmp textout=5 user must open file textout=7 same as 3 but text is appended to <program>.prt textout = filename (default extension of .prt) /NOHEADER - If this keyword is set, then the column headers will not be printed EXAMPLE: The following example shows how a multiple valued item DATAMAX can be printed as separate columns. In the WFPC2 target database, DATAMAX is an item with 4 values, one for each of the 4 chips IDL> dbopen,'wflog' IDL> dbprint,list,'entry,datamax(0),datamax(1),datamax(2),datamax(3)' SYSTEM VARIABLES: Output device controlled by non-standard system varaible !TEXTOUT, if TEXTOUT keyword is not used. NOTES: Users may want to adjust the default lines_per_page value given at the beginning of the program for their own particular printer. PROCEDURE CALLS: db_info(), db_item_info(), dbtitle(), dbxval(), textopen, textclose zparcheck HISTORY: version 2 D. Lindler Nov. 1987 (new db format) Test if user pressed 'Q' in response to /MORE W. Landsman Sep 1991 Apply STRTRIM to free form (table) output W. Landsman Dec 1992 Test for string value of TEXTOUT W. Landsman Feb 1994 William Thompson, GSFC, 3 November 1994 Modified to allow ZDBASE to be a path string. W. Landsman, GSFC, July, 1997, Use CATCH to catch errors Removed STRTRIM in table format output to handle byte values April 1999 Fixed occasional problem when /NOHEADER is supplied Sep. 1999 Only byteswap when necessary for improved performance Feb. 2000 Change loop index for table listing to type LONG W. Landsman Aug 2000 Entry vector can be any integer type W. Landsman Aug. 2001 Replace DATATYPE() with size(/TNAME) W. Landsman Nov. 2001 No page eject for TEXTOUT =5 W. Landsman Nov. 2001 No initial page eject W. Landsman Jan. 2002 Added AdjustFormat keyword W. Landsman Sep. 2002 Assume since V5.3 (STRJOIN) W. Landsman Feb. 2004 Fix display on GUI terminals W. Landsman March 2006 Remove VMS statements W. Landsman Sep 2006 Remove EXECUTE statement W. Landsman Jan 2007 Fix display of multi element items W. Landsman Aug 2010 Fix problem with linked databases W. Landsman Dec 2011
(See $IDLUTILS_DIR/goddard/pro/database/dbprint.pro)
DBPUT
NAME: DBPUT PURPOSE: Procedure to place a new value for a specified item into a data base file entry. CALLING SEQUENCE: dbput, item, val, entry INPUTS: item - item name or number val - item value(s) INPUT/OUTPUT: entry - entry (byte array) or scalar entry number. if entry is a scalar entry number then the data base file will be updated. Otherwise the change will be only made to the entry array which must be written latter using DBWRT. OPERATIONAL NOTES: If entry is a scalar entry number or the input file name is supplied, the entry in the data base will be updated instead of a supplied entry variable. In this case, !priv must be greater than 1. EXAMPLE: IDL> dbput,'WAVELEN',1215.6,entry PROCEDURES USED: DB_ITEM, DBRD, DBXPUT, DBWRT HISTORY: version 2 D. Lindler Feb 1988 (new db formats) modified to convert blanks into zeros correctly D. Neill Jan 1991 Converted to IDL V5.0 W. Landsman September 1997 V5.2 version support unsigned, 64bit integers W. Landsman Sep. 2001
(See $IDLUTILS_DIR/goddard/pro/database/dbput.pro)
DBRD
NAME: DBRD PURPOSE: procedure to read an entry from a data base file or from linked multiple databases. CALLING SEQUENCE: dbrd, enum, entry, [available, dbno, /NoConvert] INPUTS: enum - entry number to read, integer scalar OUTPUT: entry - byte array containing the entry OPTIONAL OUTPUT: available - byte array with length equal to number of data bases opened. available(i) eq 1 if an entry (pointed to) is available. It always equals 1 for the first data base, otherwise it is an error condition. OPTIONAL INPUT: dbno - specification of the data base number to return. If supplied, only the record for the requested data base number is returned in entry. Normally this input should not be supplied. dbno is numbered for 0 to n-1 and gives the number of the data base opened. The data bases are numbered in the order supplied to dbopen. If dbno is supplied then the entry number refers to that data base and not the primary or first data base. If set to -1, then it means all data bases opened (same as not supplying it) OPTIONAL INPUT KEYWORD: noconvert - if set then don't convert external to host format. Assumes that calling program will take care of this requirement. OPERATIONAL NOTES: If multiple data base files are opened, the records are concatenated with each other HISTORY version 2 D. Lindler Nov. 1987 William Thompson, GSFC/CDS (ARC), 1 June 1994 Added support for external (IEEE) representation. Version 3, Richard Schwartz, GSFC/SDAC, 23-Aug-1996 Add noconvert keyword Converted to IDL V5.0 W. Landsman September 1997 Version 4, 2 May 2003, W. Thompson Use BSWAP keyword to DBXVAL instead of calling IEEE_TO_HOST.
(See $IDLUTILS_DIR/goddard/pro/database/dbrd.pro)
DBSEARCH
NAME: DBSEARCH PURPOSE: Subroutine of DBFIND() to search a vector for specified values CALLING SEQUENCE: dbsearch, type, svals, values, good, [ /FULLSTRING, COUNT = ] INPUT: type - type of search (output from dbfparse) svals - search values (output from dbfparse) values - array of values to search OUTPUT: good - indices of good values OPTIONAL INPUT KEYWORD: /FULLSTRING - By default, one has a match if a search string is included in any part of a database value (substring match). But if /FULLSTRING is set, then all characters in the database value must match the search string (excluding leading and trailing blanks). Both types of string searches are case insensitive. OPTIONAL OUTPUT KEYWORD: COUNT - Integer scalar giving the number of valid matches SIDE EFFECTS: The obsolete system variable !ERR is set to number of good values REVISION HISTORY: D. Lindler July,1987 Added COUNT keyword, deprecate !ERR W. Landsman March 2000 Some speed improvements W.L. August 2008 Add compound operators, slightly faster WL November 2009
(See $IDLUTILS_DIR/goddard/pro/database/dbsearch.pro)
DBSORT
NAME: DBSORT PURPOSE: Routine to sort list of entries in data base CALLING SEQUENCE: result = dbsort( list, items , [ REVERSE = ]) INPUTS: list - list of entry numbers to sort -1 to sort all entries items - list of items to sort (up to 9 items) OUTPUT: result - numeric vector giving input list sorted by items OPTIONAL KEYWORD INPUT: REVERSE - scalar or vector with the same number of elements as the the number of items to sort. If the corresponding element of REVERSE is non-zero then that item is sorted in descending rather than ascending order. EXAMPLE: Sort an astronomical catalog with RA as primary sort, and declination as secondary sort (used when RA values are equal) IDL> NEWLIST = DBSORT( -1, 'RA,DEC' ) If for some reason, one wanted the DEC sorted in descending order, but the RA in ascending order IDL> NEWLIST = DBSORT( -1, 'RA,DEC', REV = [ 0, 1 ] ) METHOD: The list is sorted such that each item is sorted into asscending order starting with the last item. COMMON BLOCKS: DBCOM PROCEDURES USED: ZPARCHECK, BSORT, DBEXT, DB_ITEM HISTORY VERSION 1 D. Lindler Oct. 86 Added REVERSE keyword W. Landsman August, 1991 Avoid use of EXECUTE() for V6.1 or later W. Landsman Dec 2006 Assume since V6.1 W. Landsman June 2009 Add TEMPORARY call W. Lnadsman July 2009
(See $IDLUTILS_DIR/goddard/pro/database/dbsort.pro)
DBTARGET
NAME: DBTARGET PURPOSE: Find sources in a database within specified radius of specified target EXPLANATION: Uses QuerySimbad to translate target name to RA and Dec, and then uses DBCIRCLE() to find any entries within specified radius. Database must include items named 'RA' (in hours) and 'DEC' (in degrees) and must have previously been opened with DBOPEN CALLING SEQUENCE: list = DBTARGET(target, [radius, sublist, /SILENT, DIS= ,/TO_B1950 ] ) INPUTS: TARGET - A scalar string giving an astronomical target name, which will be translated into J2000 celestial coordinates by QuerySimbad OPTIONAL INPUT: RADIUS - Radius of the search field in arc minutes, scalar. Default is 5 arc minutes SUBLIST - Vector giving entry numbers in currently opened database to be searched. Default is to search all entries OUTPUTS: LIST - Vector giving entry numbers in the currently opened catalog which have positions within the specified search circle LIST is set to -1 if no sources fall within the search circle !ERR is set to the number sources found. OPTIONAL OUTPUT DIS - The distance in arcminutes of each entry specified by LIST to the search center specified by the target. OPTIONAL KEYWORD INPUT: /SILENT - If this keyword is set, then DBTARGET will not print the number of entries found at the terminal /TO_B1950 - If this keyword is set, then the SIMBAD J2000 coordinates are converted to B1950 before searching the database NOTE: The user must determine on his own whether the database is in B1950 or J2000 coordinates. RESTRICTIONS; The database must have items 'RA' (in hours) and 'DEC' (in degrees). Alternatively, the database could have items RA_OBJ and DEC_OBJ (both in degrees) EXAMPLE: (1) Use the HST_CATALOG database to find all HST observations within 5' (the default) of M33 IDL> dbopen,'hst_catalog' IDL> list = dbtarget('M33') (2) As above but restrict targets within 2' of the nucleus using the WFPC2 camara IDL> dbopen,'hst_catalog' IDL> sublist = dbfind('config=WFPC2') IDL> list = dbtarget('M33',2,sublist) PROCEDURE CALLS: QuerySimbad, DBCIRCLE() REVISION HISTORY: Written W. Landsman SSAI September 2002 Propagate /SILENT keyword to QuerySimbad W. Landsman Oct 2009 Make sure a database is open W.L. Oct 2010
(See $IDLUTILS_DIR/goddard/pro/database/dbtarget.pro)
DBTITLE
NAME: DBTITLE PURPOSE: function to create title line for routine dbprint CALLING SEQUENCE: result = dbtitle( c, f ) INPUTS: c = string array of titles for each item f = field length of each item OUTPUT: header string returned as function value OPERATIONAL NOTES: this is a subroutine of DBPRINT. HISTORY: version 1 D. Lindler Sept 86 Converted to IDL V5.0 W. Landsman September 1997
(See $IDLUTILS_DIR/goddard/pro/database/dbtitle.pro)
DBUPDATE
NAME: DBUPDATE PURPOSE: Update columns of data in a database -- inverse of DBEXT EXPLANATION: Database must be open for update before calling DBUPDATE CALLING SEQUENCE: dbupdate, list, items, v1, [ v2, v3, v4......v14 ] INPUTS: list - entries in database to be updated, scalar or vector If list=-1 then all entries will be updated items -standard list of items that will be updated. v1,v2....v14 - vectors containing values for specified items. The number of vectors supplied must equal the number of items specified. The number of elements in each vector should be the same. OPTIONAL KEYWORD INPUT: /NOINDEX - If set, then DBUPDATE will not update the index file. This keyword is useful to save if additional updates will occur, and the index file need only be updated on the last call. EXAMPLES: A database STAR contains RA and DEC in radians, convert to degrees IDL> !PRIV=2 & dbopen,'STAR',1 ;Open database for update IDL> dbext,-1,'RA,DEC',ra,dec ;Extract RA and DEC, all entries IDL> ra = ra*!RADEG & dec=dec*!RADEG ;Convert to degrees IDL> dbupdate,-1,'RA,DEC',ra,dec ;Update database with new values NOTES: It is quicker to update several items simultaneously rather than use repeated calls to DBUPDATE. It is possible to update multiple valued items. In this case, the input vector should be of dimension (NVAL,NLIST) where NVAL is the number of values per item, and NLIST is the number of entries to be updated. This vector will be temporarily transposed by DBUPDATE but will be restored before DBUPDATE exits. REVISION HISTORY Written W. Landsman STX March, 1989 Work for multiple valued items May, 1991 String arrays no longer need to be fixed length December 1992 Transpose multiple array items back on output December 1993 Faster update of external databases on big endian machines November 1997 Converted to IDL V5.0 W. Landsman 24-Nov-1997 Added /NOINDEX keyword W. Landsman July 2001
(See $IDLUTILS_DIR/goddard/pro/database/dbupdate.pro)
DBVAL
NAME: DBVAL PURPOSE: procedure to extract value(s) of the specified item from a data base file entry. CALLING SEQUENCE: result = dbval( entry, item ) INPUTS: entry - byte array containing the entry, or a scalar entry number item - name (string) or number (integer) of the item OUTPUT: the value(s) will be returned as the function value EXAMPLE: Extract a flux vector from entry 28 of the database FARUV ==> flux = dbval(28,'FLUX') HISTORY: version 2 D. Lindler Nov, 1987 (new db format) Converted to IDL V5.0 W. Landsman September 1997
(See $IDLUTILS_DIR/goddard/pro/database/dbval.pro)
DBWRT
NAME: DBWRT PURPOSE: procedure to update or add a new entry to a data base CALLING SEQUENCE: dbwrt, entry, [ index, append, /NoConvert ] INPUTS: entry - entry record to be updated or added if first item (entry number=0) OPTIONAL INPUTS: index - optional integer flag, if set to non zero then index file is updated. (default=0, do not update index file) (Updating the index file is time-consuming, and should normally be done after all changes have been made. append - optional integer flag, if set to non-zero the record is appended as a new entry, regardless of what the entry number in the record is. The entry number will be reset to the next entry number in the file. OUTPUTS: data base file is updated. If index is non-zero then the index file is updated. OPTIONAL INPUT KEYWORD: NoConvert - If set then don't convert to host format with an external database. Useful when the calling program decides that conversion isn't needed (i.e. on a big-endian machine), or takes care of the conversion itself. OPERATIONAL NOTES: !PRIV must be greater than 1 to execute HISTORY: version 2 D. Lindler Feb. 1988 (new db format) converted to IDL Version 2. M. Greason, STX, June 1990. William Thompson, GSFC/CDS (ARC), 28 May 1994 Added support for external (IEEE) representation. Faster handling of byte swapping W. L. August 2010
(See $IDLUTILS_DIR/goddard/pro/database/dbwrt.pro)
DBXPUT
NAME: DBXPUT PURPOSE: routine to replace value of an item in a data base entry CALLING SEQUENCE: dbxput, val, entry, idltype, sbyte, nbytes INPUT: val - value(s) to be placed into entry, string values might be truncated to fit number of allowed bytes in item entry - entry or entries to be updated idltype - idl data type for item (1-7) sbyte - starting byte in record nbytes - total number of bytes in value added OUTPUT: entry - (updated) OPERATIONAL NOTES: This routine assumes that the calling procedure or user knows what he or she is doing. String items are truncated or padded to the fixed size specified by the database but otherwise no validity checks are made. HISTORY: version 1, D. Lindler Aug, 1986 converted to IDL Version 2. M. Greason, STX, June 1990. Work with multiple element string items W. Landsman August 1995 Really work with multiple element string items R. Bergman/W. Landsman July 1996 Work with multiple entries, R. Schwartz, GSFC/SDAC August 1996 Use /overwrite with REFORM() W. Landsman May 1997 Converted to IDL V5.0 W. Landsman September 1997
(See $IDLUTILS_DIR/goddard/pro/database/dbxput.pro)
DBXVAL
NAME: DBXVAL PURPOSE: Quickly return a value of the specified item number EXPLANATION: Procedure to quickly return a value of the specified item number from the entry. CALLING SEQUENCE: result = dbxval( entry, idltype, nvalues, sbyte, nbytes ) INPUTS entry - entry or entries from data base (bytarr) idltype - idl data type (obtained with db_item_info) nvalues - number of values to return (obtained with db_item) sbyte - starting byte in the entry (obtained with db_item) nbytes - number of bytes (needed only for string type) (obtained with db_item) OUTPUTS: function value is value of the specified item in entry KEYWORDS: bswap - If set, then IEEE_TO_HOST is called. RESTRICTIONS: To increase speed the routine assumes that entry and item are valid and that the data base is already opened using dbopen. REVISION HISTORY: version 0 D. Lindler Nov. 1987 (for new db format) Version 1, William Thompson, GSFC, 28 March 1994. Incorporated into CDS library. Version 2, Richard Schwartz, GSFC/SDAC, 23 August 1996 Allowed Entry to have 2 dimensions Version 2.1, 22 Feb 1997, JK Feggans, avoid reform for strings arrays. Version 2.2 Use overwrite with REFORM(), W. Landsman, May 1997 Converted to IDL V5.0 W. Landsman September 1997 Work for multiple-valued strings W. Landsman October 2000 Add new 64bit & unsigned integer datatypes W.Landsman July 2001 Version 3, 2-May-2003, JK Feggans/Sigma, W.T. Thompson Added BSWAP keyword to avoid floating errors on some platforms.
(See $IDLUTILS_DIR/goddard/pro/database/dbxval.pro)
DB_ENT2EXT
NAME: DB_ENT2EXT PURPOSE: Convert a database entry to external (IEEE) data format EXPLANATION: Converts a database entry to external (IEEE) data format prior to writing it. Called from DBWRT. CALLING SEQUENCE: DB_ENT2EXT, ENTRY INPUTS: ENTRY = Byte array containing a single record to be written to the database file. OUTPUTS: ENTRY = The converted array is returned in place of the input array. COMMON BLOCKS: DB_COM HISTORY: Version 1, William Thompson, GSFC/CDS (ARC), 1 June 1994 Version 2, William Thompson, GSFC/CDS (ARC), 15 September 1995 Fixed bug where only the first element in a multidimensional array was converted. Version 2.1 W. Landsman August 2010 Fix for multidimensional strings Version 2.2 W. Landsman Sep 2011 Work with new DB format
(See $IDLUTILS_DIR/goddard/pro/database/db_ent2ext.pro)
DB_ENT2HOST
NAME: DB_ENT2HOST PURPOSE: Converts a database entry from external data format to host format. EXPLANATION: All items are extracted from the entry, and then converted to host format, and placed back into the entry. Called from DBRD and DBEXT_DBF. CALLING SEQUENCE: DB_ENT2HOST, ENTRY, DBNO INPUTS: ENTRY = Byte array containing a single record read from the database file. DBNO = Number of the opened database file. OUTPUTS: ENTRY = The converted array is returned in place of the input array. COMMON BLOCKS: DB_COM HISTORY: Version 1, William Thompson, GSFC/CDS (ARC), 1 June 1994 Version 2, William Thompson, GSFC/CDS (ARC), 15 September 1995 Fixed bug where only the first element in a multidimensional array was converted. Version 3, Richard Schwartz, GSFC/SDAC, 23 August 1996 Allow 2 dimensional byte arrays for entries to facilitate multiple entry processing. Pass IDLTYPE onto IEEE_TO_HOST Version 4, 2 May 2003, W. Thompson Use BSWAP keyword to DBXVAL instead of calling IEEE_TO_HOST. Version 4.1 W. Landsman August 2010 Fix for multidimensional strings Version 4.2 W. Landsman Sep 2011 Work with new DB format
(See $IDLUTILS_DIR/goddard/pro/database/db_ent2host.pro)
DB_INFO
NAME: DB_INFO PURPOSE: Function to obtain information on opened data base file(s) CALLING SEQUENCES: 1) result = db_info(request) 2) result = db_info(request,dbname) INPUTS (calling sequence 1): request - string specifying requested value(s) value of request value returned in result 'open' Flag set to 1 if data base(s) are opened 'number' Number of data base files opened 'items' Total number of items (all db's opened) 'update' update flag (1 if opened for update) 'unit_dbf' Unit number of the .dbf files 'unit_dbx' Unit number of the .dbx files 'entries' Number of entries in the db's 'length' Record lengths for the db's 'external' True if the db's are in external format INPUTS (calling sequence 2): request - string specifying requested value(s) value of request value returned in result 'name' Name of the data base 'number' Sequential number of the db 'items' Number of items for this db 'item1' Position of item1 for this db in item list for all db's 'item2' Position of last item for this db. 'pointer' Number of the item which points to this db. 0 for first or primary db. -1 if link file pointers. 'length' Record length for this db. 'title' Title of the data base 'unit_dbf' Unit number of the .dbf file 'unit_dbx' Unit number of the .dbx file 'entries' Number of entries in the db 'seqnum' Last sequence number used 'alloc' Allocated space (# entries) 'update' 1 if data base opened for update 'external' True if data base in external format 'newdb' True if new (post Oct 2010) format that allows entries > 32767 bytes dbname - data base name or number OUTPUTS: Requested value(s) are returned as the function value. HISTORY: version 1 D. Lindler Oct. 1987 changed type from 1 to 7 for IDLV2, J. Isensee, Nov., 1990 William Thompson, GSFC/CDS (ARC), 30 May 1994 Added EXTERNAL request type. Support new DB format, add NEWDB request type W. Landsman Oct 2010
(See $IDLUTILS_DIR/goddard/pro/database/db_info.pro)
DB_ITEM
NAME: DB_ITEM PURPOSE: Returns the item numbers and other info. for an item name. EXPLANATION: Procedure to return the item numbers and other information of a specified item name CALLING SEQUENCE: db_item, items, itnum, ivalnum, idltype, sbyte, numvals, nbytes INPUTS: items - item name or number form 1 scalar string giving item(s) as list of names separated by commas form 2 string array giving list of item names form 3 string of form '$filename' giving name of text file containing items (one item per line) form 4 integer scalar giving single item number or integer vector list of item numbers form 5 Null string specifying interactive selection Upon return items will contain selected items in form 1 form 6 '*' select all items OUTPUTS: itnum - item number ivalnum - value(s) number from multiple valued item idltype - data type(s) (1=string,2=byte,4=i*4,...) sbyte - starting byte(s) in entry numvals - number of data values for item(s) It is the full length of a vector item unless a subscript was supplied nbytes - number of bytes for each value All outputs are vectors even if a single item is requested OPTIONAL INPUT KEYWORDS: ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. In order to use this feature, ERRMSG must be defined first, e.g. ERRMSG = '' DB_ITEM, ERRMSG=ERRMSG, ... IF ERRMSG NE '' THEN ... PROCEDURE CALLS: DB_INFO, GETTOK, SELECT_W REVISION HISTORY: Written: D. Lindler, GSFC/HRS, October 1987 Version 2, William Thompson, GSFC, 17-Mar-1997 Added keyword ERRMSG Use STRSPLIT instead of GETTOK to parse form 1, W. Landsman July 2002 Assume since V5.4 use FILE_EXPAND_PATH() instead of SPEC_DIR() W. Landsman April 2006 Support new DB format allowing entry lengths > 32767 bytes WL Oct 2010 Ignore blank lines in .items file WL February 2011
(See $IDLUTILS_DIR/goddard/pro/database/db_item.pro)
DB_ITEM_INFO
NAME: DB_ITEM_INFO PURPOSE: routine to return information on selected item(s) in the opened data bases. CALLING SEQUENCE: result = db_item_info( request, itnums) INPUTS: request - string giving the requested information. 'name' - item names 'idltype' - IDL data type (integers) see documentation of intrinsic SIZE funtion 'nvalues' - vector item length (1 for scalar) 'sbyte' - starting byte in .dbf record (use bytepos to get starting byte in record returned by dbrd) 'nbytes' - bytes per data value 'index' - index types 'description' - description of the item 'pflag' - pointer item flags 'pointer' - data bases the items point to 'format' - print formats 'flen' - print field length 'headers' - print headers 'bytepos' - starting byte in dbrd record for the items 'dbnumber' - number of the opened data base 'pnumber' - number of db it points to (if the db is opened) 'itemnumber' - item number in the file itnums -(optional) Item numbers. If not supplied info on all items are returned. OUTPUT: Requested information is returned as a vector. Its type depends on the item requested. HISTORY: version 1 D. Lindler Nov. 1987 Converted to IDL V5.0 W. Landsman September 1997 Support new DB format which allows > 32767 bytes W.L. Oct 2010
(See $IDLUTILS_DIR/goddard/pro/database/db_item_info.pro)
DB_OR
NAME: DB_OR PURPOSE: Combine two vectors of entry numbers, removing duplicate values. EXPLANATION: DB_OR can also be used to remove duplicate values from any longword vector CALLING SEQUENCE: LIST = DB_OR( LIST1 ) ;Remove duplicate values from LIST1 or LIST = DB_OR( LIST1, LIST2 ) ;Concatenate LIST1 and LIST2, remove dups INPUTS: LIST1, LIST2 - Vectors containing entry numbers, must be non-negative integers or longwords. OUTPUT: LIST - Vector containing entry numbers in either LIST1 or LIST2 METHOD DB_OR returns where the histogram of the entry vectors is non-zero PROCEDURE CALLS ZPARCHECK - checks parameters REVISION HISTORY: Written, W. Landsman February, 1989 Check for degenerate values W.L. February, 1993 Converted to IDL V5.0 W. Landsman September 1997
(See $IDLUTILS_DIR/goddard/pro/database/db_or.pro)
DB_TITLES
NAME: DB_TITLES PURPOSE: Print database name and title. Called by DBHELP CALLING SEQUENCE: db_titles, fnames, titles INPUT: fnames - string array of data base names SIDE EFFECT: Database name is printed along with the description in the .dbh file HISTORY: version 2 W. Landsman May, 1989 modified to work under Unix, D. Neill, ACC, Feb 1991. William Thompson, GSFC/CDS (ARC), 1 June 1994 Added support for external (IEEE) representation. William Thompson, GSFC, 3 November 1994 Modified to allow ZDBASE to be a path string. Converted to IDL V5.0 W. Landsman September 1997 Assume since V5.5, W. Landsman September 2006
(See $IDLUTILS_DIR/goddard/pro/database/db_titles.pro)
DECOMPOSEDCOLOR
NAME: DECOMPOSEDCOLOR PURPOSE: This function is used to determine, in a device independent way, if the current graphics device is using color decomposition. The function returns a 1 if color decomposition is turned on, and a 0 if it is turned off. When color decomposition is turned on, we say the device is using a true-color display. If color decomposition is turned off, we say the device is using an indexed color display. AUTHOR: FANNING SOFTWARE CONSULTING David Fanning, Ph.D. 1645 Sheely Drive Fort Collins, CO 80526 USA Phone: 970-221-0438 E-mail: david@idlcoyote.com Coyote's Guide to IDL Programming: http://www.idlcoyote.com/ CATEGORY: Utilities CALLING SEQUENCE: result = DecomposedColor() RETURN VALUE: result: A 1 if color decomposition is turned on. A 0 if color decomposition is turned off. ARGUMENTS: device: The IDL graphics device whose color decomposition state you wish to know the current value of. If undefined, the current graphics device is used. KEYWORDRS: DEPTH: An output keyword that returns the depth of the graphics device. Normally, either 8 for index color devices, with color decomposition turned off, or 24 for true-color devices with color decomposition turned on. EXAMPLE: IDL> Print, DecomposedColor() ; Color decomposition state of current graphics device. 1 IDL> Print, DecomposedColor('PS') ; Color decomposition state of PostScript graphics device. 0 MODIFICATION HISTORY: Written by: David W. Fanning, May 24, 2009. Modified the way decomposition was obtained for PostScript devices IDL 7.1 and higher. 12 Dec 2010. DWF. Fixed a problem in the CASE statement with ELSE clause and added a NULL device segment. 4 Jan 2011. DWF. It now appears 24-bit PostScript support was added in IDL 7.1, although the Get_Decomposed keyword didn't work until IDL 7.1.1. 13 January 2011. DWF
(See $IDLUTILS_DIR/goddard/pro/coyote/decomposedcolor.pro)
DELVARX
NAME: DELVARX PURPOSE: Delete up to 10 variables for memory management (can call from routines) EXPLANATION: Like intrinsic DELVAR function, but can be used from any calling level Modified in January 2012 to always free memory associated with pointers/objects and remove the use EXECUTE() CALLING SEQUENCE: DELVARX, p0, [p1, p2......p9] INPUTS: p0, p1...p9 - variables to delete OBSOLETE KEYWORD: /FREE_MEM - formerly freed memory associated with pointers and objects. Since this is now the DELVARX default this keyword does nothing. METHOD: Uses HEAP_FREE and PTR_NEW(/NO_COPY) to delete variables and free memory REVISION HISTORY: Copied from the Solar library, written by slf, 25-Feb-1993 Added to Astronomy Library, September 1995 Modified, 26-Mar-2003, Zarro (EER/GSFC) 26-Mar-2003 - added FREE_MEM to free pointer/objects Modified, 28-Jan-2012, E. Rykoff (SLAC), W. Landsman - replace EXECUTE calls with SCOPE_VARFETCH.
(See $IDLUTILS_DIR/goddard/pro/misc/delvarx.pro)
DEREDD
NAME: DEREDD PURPOSE: Deredden stellar Stromgren parameters given for a value of E(b-y) EXPLANATION: See the procedure UVBYBETA for more info. CALLING SEQUENCE: deredd, eby, by, m1, c1, ub, by0, m0, c0, ub0, /UPDATE INPUTS: Eby - color index E(b-y),scalar (E(b-y) = 0.73*E(B-V) ) by - b-y color (observed) m1 - Stromgren line blanketing parameter (observed) c1 - Stromgren Balmer discontinuity parameter (observed) ub - u-b color (observed) These input values are unaltered unless the /UPDATE keyword is set OUTPUTS: by0 - b-y color (dereddened) m0 - Line blanketing index (dereddened) c0 - Balmer discontinuity parameter (dereddened) ub0 - u-b color (dereddened) OPTIONAL INPUT KEYWORDS: /UPDATE - If set, then input parameters are updated with the dereddened values (and output parameters are not used). REVISION HISTORY: Adapted from FORTRAN routine DEREDD by T.T. Moon W. Landsman STX Co. April, 1988 Converted to IDL V5.0 W. Landsman September 1997
(See $IDLUTILS_DIR/goddard/pro/astro/deredd.pro)
DETABIFY
NAME: DETABIFY PURPOSE: Replaces tabs in character strings with appropriate number of spaces EXPLANATION: The number of space characters inserted is calculated to space out to the next effective tab stop, each of which is eight characters apart. CALLING SEQUENCE: Result = DETABIFY( CHAR_STR ) INPUT PARAMETERS: CHAR_STR = Character string variable (or array) to remove tabs from. OUTPUT: Result of function is CHAR_STR with tabs replaced by spaces. RESTRICTIONS: CHAR_STR must be a character string variable. MODIFICATION HISTORY: William Thompson, Feb. 1992. Converted to IDL V5.0 W. Landsman September 1997
(See $IDLUTILS_DIR/goddard/pro/misc/detabify.pro)
DIST_CIRCLE
NAME: DIST_CIRCLE PURPOSE: Form a square array where each value is its distance to a given center. EXPLANATION: Returns a square array in which the value of each element is its distance to a specified center. Useful for circular aperture photometry. CALLING SEQUENCE: DIST_CIRCLE, IM, N, [ XCEN, YCEN, /DOUBLE ] INPUTS: N = either a scalar specifying the size of the N x N square output array, or a 2 element vector specifying the size of the N x M rectangular output array. OPTIONAL INPUTS: XCEN,YCEN = Scalars designating the X,Y pixel center. These need not be integers, and need not be located within the output image. If not supplied then the center of the output image is used (XCEN = YCEN = (N-1)/2.). OUTPUTS: IM - N by N (or M x N) floating array in which the value of each pixel is equal to its distance to XCEN,YCEN OPTIONAL INPUT KEYWORD: /DOUBLE - If this keyword is set and nonzero, the output array will be of type DOUBLE rather than floating point. EXAMPLE: Total the flux in a circular aperture within 3' of a specified RA and DEC on an 512 x 512 image IM, with a header H. IDL> adxy, H, RA, DEC, x, y ;Convert RA and DEC to X,Y IDL> getrot, H, rot, cdelt ;CDELT gives plate scale deg/pixel IDL> cdelt = cdelt*3600. ;Convert to arc sec/pixel IDL> dist_circle, circle, 512, x, y ;Create a distance circle image IDL> circle = circle*abs(cdelt[0]) ;Distances now given in arcseconds IDL> good = where(circle LT 180) ;Within 3 arc minutes IDL> print,total( IM[good] ) ;Total pixel values within 3' RESTRICTIONS: The speed of DIST_CIRCLE decreases and the the demands on virtual increase as the square of the output dimensions. Users should dimension the output array as small as possible, and re-use the array rather than re-calling DIST_CIRCLE MODIFICATION HISTORY: Adapted from DIST W. Landsman March 1991 Allow a rectangular output array W. Landsman June 1994 Converted to IDL V5.0 W. Landsman September 1997 Add /DOUBLE keyword, make XCEN,YCEN optional W. Landsman Jun 1998
(See $IDLUTILS_DIR/goddard/pro/image/dist_circle.pro)
DIST_ELLIPSE
NAME: DIST_ELLIPSE PURPOSE: Create a mask array useful for elliptical aperture photemetry EXPLANATION: Form an array in which the value of each element is equal to the semi-major axis of the ellipse of specified center, axial ratio, and position angle, which passes through that element. Useful for elliptical aperture photometry. CALLING SEQUENCE: DIST_ELLIPSE, IM, N, XC, YC, RATIO, POS_ANG, /DOUBLE INPUTS: N = either a scalar specifying the size of the N x N square output array, or a 2 element vector specifying the size of the M x N rectangular output array. XC,YC - Scalars giving the position of the ellipse center. This does not necessarily have to be within the image RATIO - Scalar giving the ratio of the major to minor axis. This should be greater than 1 for postion angle to have its standard meaning. OPTIONAL INPUTS: POS_ANG - Position angle of the major axis, measured counter-clockwise from the Y axis. For an image in standard orientation (North up, East left) this is the astronomical position angle. OPTIONAL INPUT KEYWORD: /DOUBLE - If this keyword is set and nonzero, the output array will be of type DOUBLE rather than floating point. OUTPUT: IM - REAL*4 elliptical mask array, of size M x N. THe value of each pixel is equal to the semi-major axis of the ellipse of center XC,YC, axial ratio RATIO, and position angle POS_ANG, which passes through the pixel. EXAMPLE: Total the flux in a elliptical aperture with a major axis of 3', an axial ratio of 2.3, and a position angle of 25 degrees centered on a specified RA and DEC. The image array, IM is 200 x 200, and has an associated FITS header H. ADXY, H, ra, dec, x, y ;Get X and Y corresponding to RA and Dec GETROT, H, rot, cdelt ;CDELT gives plate scale degrees/pixel cdelt = abs( cdelt)*3600. ;CDELT now in arc seconds/pixel DIST_ELLIPSE, ell, 200, x, y, 2.3, 25 ;Create a elliptical image mask ell = ell*cdelt(0) ;Distances now given in arcseconds good = where( ell lt 180 ) ;Within 3 arc minutes print,total( im(good) ) ;Total pixel values within 3' RESTRICTIONS: The speed of DIST_ELLIPSE decreases and the the demands on virtual increase as the square of the output dimensions. Users should dimension the output array as small as possible, and re-use the array rather than re-calling DIST_ELLIPSE REVISION HISTORY: Written W. Landsman April, 1991 Somewhat faster algorithm August, 1992 Allow rectangular output array June, 1994 Converted to IDL V5.0 W. Landsman September 1997 Added /DOUBLE keyword W. Landsman July 2000
(See $IDLUTILS_DIR/goddard/pro/image/dist_ellipse.pro)
ECI2GEO
NAME: ECI2GEO PURPOSE: Convert Earth-centered inertial coordinates to geographic spherical coords EXPLANATION: Converts from ECI (Earth-Centered Inertial) (X,Y,Z) rectangular coordinates to geographic spherical coordinates (latitude, longitude, altitude). JD time is also needed as input. ECI coordinates are in km from Earth center. Geographic coordinates are in degrees/degrees/km Geographic coordinates assume the Earth is a perfect sphere, with radius equal to its equatorial radius. CALLING SEQUENCE: gcoord=eci2geo(ECI_XYZ,JDtime) INPUT: ECI_XYZ : the ECI [X,Y,Z] coordinates (in km), can be an array [3,n] of n such coordinates. JDtime: the Julian Day time, double precision. Can be a 1-D array of n such times. KEYWORD INPUTS: None OUTPUT: a 3-element array of geographic [latitude,longitude,altitude], or an array [3,n] of n such coordinates, double precision COMMON BLOCKS: None PROCEDURES USED: CT2LST - Convert Local Civil Time to Local Mean Sidereal Time EXAMPLE: IDL> gcoord=eci2geo([6378.137+600,0,0], 2452343.38982663D) IDL> print,gcoord 0.0000000 232.27096 600.00000 (The above is the geographic direction of the vernal point on 2002/03/09 21:21:21.021, in geographic coordinates. The chosen altitude was 600 km.) gcoord can be further transformed into geodetic coordinates (using geo2geodetic.pro) or into geomagnetic coordinates (using geo2mag.pro) MODIFICATION HISTORY: Written by Pascal Saint-Hilaire (Saint-Hilaire@astro.phys.ethz.ch) on 2001/05/13 Modified on 2002/05/13, PSH : vectorization + use of JD times
(See $IDLUTILS_DIR/goddard/pro/astro/eci2geo.pro)
EQ2HOR
NAME: EQ2HOR PURPOSE: Convert celestial (ra-dec) coords to local horizon coords (alt-az). CALLING SEQUENCE: eq2hor, ra, dec, jd, alt, az, [ha, LAT= , LON= , /WS, OBSNAME= , $ /B1950 , PRECESS_= 0, NUTATE_= 0, REFRACT_= 0, $ ABERRATION_= 0, ALTITUDE= , /VERBOSE, _EXTRA= ] DESCRIPTION: This is a nice code to calculate horizon (alt,az) coordinates from equatorial (ra,dec) coords. It is typically accurate to about 1 arcsecond or better (I have checked the output against the publicly available XEPHEM software). It performs precession, nutation, aberration, and refraction corrections. The perhaps best thing about it is that it can take arrays as inputs, in all variables and keywords EXCEPT Lat, lon, and Altitude (the code assumes these aren't changing), and uses vector arithmetic in every calculation except when calculating the precession matrices. INPUT VARIABLES: RA : Right Ascension of object (J2000) in degrees (FK5); scalar or vector. Dec : Declination of object (J2000) in degrees (FK5), scalar or vector. JD : Julian Date [scalar or vector] Note: if RA and DEC are arrays, then alt and az will also be arrays. If RA and DEC are arrays, JD may be a scalar OR an array of the same dimensionality. OPTIONAL INPUT KEYWORDS: lat : north geodetic latitude of location in degrees lon : EAST longitude of location in degrees (Specify west longitude with a negative sign.) /WS : Set this to get the azimuth measured westward from south (not East of North). obsname: Set this to a valid observatory name to be used by the astrolib OBSERVATORY procedure, which will return the latitude and longitude to be used by this program. /B1950 : Set this if your ra and dec are specified in B1950, FK4 coordinates (instead of J2000, FK5) precess_ : Set this to 1 to force precession [default], 0 for no precession correction nutate_ : Set this to 1 to force nutation [default], 0 for no nutation. aberration_ : Set this to 1 to force aberration correction [default], 0 for no correction. refract_ : Set to 1 to force refraction correction [default], 0 for no correction. altitude: The altitude of the observing location, in meters. [default=0]. verbose: Set this for verbose output. The default is verbose=0. _extra: This is for setting TEMPERATURE or PRESSURE explicitly, which are used by CO_REFRACT to calculate the refraction effect of the atmosphere. If you don't set these, the program will make an intelligent guess as to what they are (taking into account your altitude). See CO_REFRACT for more details. OUTPUT VARIABLES: (all double precision) alt : altitude (in degrees) az : azimuth angle (in degrees, measured EAST from NORTH, but see keyword WS above.) ha : hour angle (in degrees) (optional) DEPENDENCIES: NUTATE, PRECESS, OBSERVATORY, SUNPOS, ADSTRING() (from the astrolib) CO_NUTATE, CO_ABERRATION, CO_REFRACT, ALTAZ2HADEC BASIC STEPS Apply refraction correction to find apparent Alt. Calculate Local Mean Sidereal Time Calculate Local Apparent Sidereal Time Do Spherical Trig to find apparent hour angle, declination. Calculate Right Ascension from hour angle and local sidereal time. Nutation Correction to Ra-Dec Aberration correction to Ra-Dec Precess Ra-Dec to current equinox. CORRECTIONS I DO NOT MAKE: * Deflection of Light by the sun due to GR. (typically milliarcseconds, can be arseconds within one degree of the sun) * The Effect of Annual Parallax (typically < 1 arcsecond) * and more (see below) TO DO * Better Refraction Correction. Need to put in wavelength dependence, and integrate through the atmosphere. * Topocentric Parallax Correction (will take into account elevation of the observatory) * Proper Motion (but this will require crazy lookup tables or something). * Difference between UTC and UT1 in determining LAST -- is this important? * Effect of Annual Parallax (is this the same as topocentric Parallax?) * Polar Motion * Better connection to Julian Date Calculator. EXAMPLE Find the position of the open cluster NGC 2264 at the Effelsburg Radio Telescope in Germany, on June 11, 2023, at local time 22:00 (METDST). The inputs will then be: Julian Date = 2460107.250 Latitude = 50d 31m 36s Longitude = 06h 51m 18s Altitude = 369 meters RA (J2000) = 06h 40m 58.2s Dec(J2000) = 09d 53m 44.0s IDL> eq2hor, ten(6,40,58.2)*15., ten(9,53,44), 2460107.250d, alt, az, $ lat=ten(50,31,36), lon=ten(6,51,18), altitude=369.0, /verb, $ pres=980.0, temp=283.0 The program produces this output (because the VERBOSE keyword was set) Latitude = +50 31 36.0 Longitude = +06 51 18.0 Julian Date = 2460107.250000 Ra, Dec: 06 40 58.2 +09 53 44.0 (J2000) Ra, Dec: 06 42 15.7 +09 52 19.2 (J2023.4422) Ra, Dec: 06 42 13.8 +09 52 26.9 (fully corrected) LMST = +11 46 42.0 LAST = +11 46 41.4 Hour Angle = +05 04 27.6 (hh:mm:ss) Az, El = 17 42 25.6 +16 25 10.3 (Apparent Coords) Az, El = 17 42 25.6 +16 28 22.8 (Observer Coords) Compare this with the result from XEPHEM: Az, El = 17h 42m 25.6s +16d 28m 21s This 1.8 arcsecond discrepancy in elevation arises primarily from slight differences in the way I calculate the refraction correction from XEPHEM, and is pretty typical. AUTHOR: Chris O'Dell Univ. of Wisconsin-Madison Observational Cosmology Laboratory Email: odell@cmb.physics.wisc.edu
(See $IDLUTILS_DIR/goddard/pro/astro/eq2hor.pro)
EQPOLE
NAME: EQPOLE PURPOSE: Convert RA and Dec to X,Y using an equal-area polar projection. EXPLANATION: The output X and Y coordinates are scaled to be between -90 and +90 to go from equator to pole to equator. Output map points can be centered on the north pole or south pole. CALLING SEQUENCE: EQPOLE, L, B, X, Y, [ /SOUTHPOLE ] INPUTS: L - longitude - scalar or vector, in degrees B - latitude - same number of elements as RA, in degrees OUTPUTS: X - X coordinate, same number of elements as RA. X is normalized to be between -90 and 90. Y - Y coordinate, same number of elements as DEC. Y is normalized to be between -90 and 90. KEYWORDS: /SOUTHPOLE - Keyword to indicate that the plot is to be centered on the south pole instead of the north pole. REVISION HISTORY: J. Bloch LANL, SST-9 1.1 5/16/91 Converted to IDL V5.0 W. Landsman September 1997
(See $IDLUTILS_DIR/goddard/pro/astro/eqpole.pro)
EQPOLE_GRID
NAME: EQPOLE_GRID PURPOSE: Produce an equal area polar projection grid overlay EXPLANATION: Grid is written on the current graphics device using the equal area polar projection. EQPOLE_GRID assumes that the output plot coordinates span the x and y ranges of -90 to 90 for a region that covers the equator to the chosen pole. The grid is assumed to go from the equator to the chosen pole. CALLING SEQUENCE: EQPOLE_GRID[,DLONG,DLAT,[/SOUTHPOLE, LABEL = , /NEW, _EXTRA=] INPUTS: DLONG = Optional input longitude line spacing in degrees. If left out, defaults to 30. DLAT = Optional input lattitude line spacing in degrees. If left out, defaults to 30. INPUT KEYWORDS: /SOUTHPOLE = Optional flag indicating that the output plot is to be centered on the south rather than the north pole. LABEL = Optional flag for creating labels on the output grid on the prime meridian and the equator for lattitude and longitude lines. If set =2, then the longitude lines are labeled in hours and minutes. CHARSIZE = If /LABEL is set, then CHARSIZE specifies the size of the label characters (passed to XYOUTS) CHARTHICK = If /LABEL is set, then CHARTHICK specifies the thickness of the label characters (passed to XYOUTS) /NEW = If this keyword is set, then EQPOLE_GRID will create a new plot, rather than overlay an existing plot. Any valid keyword to OPLOT such as COLOR, LINESTYLE, THICK can be passed to AITOFF_GRID (though the _EXTRA facility) to to specify the color, style, or thickness of the grid lines. OUTPUTS: Draws grid lines on current graphics device. EXAMPLE: Create a labeled equal area projection grid of the Galaxy, centered on the South pole, and overlay stars at specified Galactic longitudes, glong and latitudes, glat IDL> eqpole_grid,/label,/new,/south ;Create labeled grid IDL> eqpole, glong, glat, x,y ;Convert to X,Y coordinates IDL> plots,x,y,psym=2 ;Overplot "star" positions. COPYRIGHT NOTICE: Copyright 1992, The Regents of the University of California. This software was produced under U.S. Government contract (W-7405-ENG-36) by Los Alamos National Laboratory, which is operated by the University of California for the U.S. Department of Energy. The U.S. Government is licensed to use, reproduce, and distribute this software. Neither the Government nor the University makes any warranty, express or implied, or assumes any liability or responsibility for the use of this software. AUTHOR AND MODIFICATIONS: J. Bloch 1.4 10/28/92 Converted to IDL V5.0 W. Landsman September 1997 Create default plotting coords, if needed W. Landsman August 2000 Added _EXTRA, CHARTHICK, CHARSIZE keywords W. Landsman March 2001
(See $IDLUTILS_DIR/goddard/pro/astro/eqpole_grid.pro)
ERROR_MESSAGE
NAME: ERROR_MESSAGE PURPOSE: The purpose of this function is to have a device-independent error messaging function. The error message is reported to the user by using DIALOG_MESSAGE if widgets are supported and MESSAGE otherwise. In general, the ERROR_MESSAGE function is not called directly. Rather, it is used in a CATCH error handler. Errors are thrown to ERROR_MESSAGE with the MESSAGE command. A typical CATCH error handler is shown below. Catch, theError IF theError NE 0 THEN BEGIN Catch, /Cancel void = Error_Message() RETURN ENDIF Error messages would get into the ERROR_MESSAGE function by throwing an error with the MESSAGE command, like this: IF test NE 1 THEN Message, 'The test failed.' AUTHOR: FANNING SOFTWARE CONSULTING David Fanning, Ph.D. 1645 Sheely Drive Fort Collins, CO 80526 USA Phone: 970-221-0438 E-mail: david@idlcoyote.com Coyote's Guide to IDL Programming: http://www.idlcoyote.com/ CATEGORY: Utility. CALLING SEQUENCE: ok = Error_Message(the_Error_Message) INPUTS: the_Error_Message: This is a string argument containing the error message you want reported. If undefined, this variable is set to the string in the !Error_State.Msg system variable. KEYWORDS: ERROR: Set this keyword to cause Dialog_Message to use the ERROR reporting dialog. Note that a bug in IDL causes the ERROR dialog to be used whether this keyword is set to 0 or 1! INFORMATIONAL: Set this keyword to cause Dialog_Message to use the INFORMATION dialog instead of the WARNING dialog. Note that a bug in IDL causes the ERROR dialog to be used if this keyword is set to 0! NONAME: Normally, the name of the routine in which the error occurs is added to the error message. Setting this keyword will suppress this behavior. TITLE: Set this keyword to the title of the DIALOG_MESSAGE window. By default the keyword is set to 'System Error' unless !ERROR_STATE.NAME equals "IDL_M_USER_ERR", in which case it is set to "Trapped Error'. TRACEBACK: Setting this keyword results in an error traceback being printed to standard output with the PRINT command. Set to 1 (ON) by default. Use TRACEBACK=0 to turn this functionality off. QUIET: Set this keyword to suppress the DIALOG_MESSAGE pop-up dialog. OUTPUTS: Currently the only output from the function is the string "OK". RESTRICTIONS: The WARNING Dialog_Message dialog is used by default. EXAMPLE: To handle an undefined variable error: IF N_Elements(variable) EQ 0 THEN $ ok = Error_Message('Variable is undefined') MODIFICATION HISTORY: Written by: David W. Fanning, 27 April 1999. Added the calling routine's name in the message and NoName keyword. 31 Jan 2000. DWF. Added _Extra keyword. 10 February 2000. DWF. Forgot to add _Extra everywhere. Fixed for MAIN errors. 8 AUG 2000. DWF. Adding call routine's name to Traceback Report. 8 AUG 2000. DWF. Added ERROR, INFORMATIONAL, and TITLE keywords. 19 SEP 2002. DWF. Removed the requirement that you use the NONAME keyword with the MESSAGE command when generating user-trapped errors. 19 SEP 2002. DWF. Added distinctions between trapped errors (errors generated with the MESSAGE command) and IDL system errors. Note that if you call ERROR_MESSAGE directly, then the state of the !ERROR_STATE.NAME variable is set to the *last* error generated. It is better to access ERROR_MESSAGE indirectly in a Catch error handler from the MESSAGE command. 19 SEP 2002. DWF. Change on 19 SEP 2002 to eliminate NONAME requirement did not apply to object methods. Fixed program to also handle messages from object methods. 30 JULY 2003. DWF. Removed obsolete STR_SEP and replaced with STRSPLIT. 27 Oct 2004. DWF. Made a traceback the default case without setting TRACEBACK keyword. 19 Nov 2004. DWF. Added check for window connection specifically for CRON jobs. 6 May 2008. DWF. Added QUIET keyword. 18 October 2008. DWF. The traceback information was bypassed when in the PostScript device. Not what I had in mind. Fixed. 6 July 2009. DWF.
(See $IDLUTILS_DIR/goddard/pro/coyote/error_message.pro)
EULER
NAME: EULER PURPOSE: Transform between Galactic, celestial, and ecliptic coordinates. EXPLANATION: Use the procedure ASTRO to use this routine interactively CALLING SEQUENCE: EULER, AI, BI, AO, BO, [ SELECT, /FK4, /RADIAN, SELECT = ] INPUTS: AI - Input Longitude, scalar or vector. In DEGREES unless /RADIAN is set. If only two parameters are supplied, then AI and BI will be modified to contain the output longitude and latitude. BI - Input Latitude in DEGREES OPTIONAL INPUT: SELECT - Integer (1-6) specifying type of coordinate transformation. SELECT From To | SELECT From To 1 RA-Dec (2000) Galactic | 4 Ecliptic RA-Dec 2 Galactic RA-DEC | 5 Ecliptic Galactic 3 RA-Dec Ecliptic | 6 Galactic Ecliptic If not supplied as a parameter or keyword, then EULER will prompt for the value of SELECT Celestial coordinates (RA, Dec) should be given in equinox J2000 unless the /FK4 keyword is set. OUTPUTS: AO - Output Longitude in DEGREES, always double precision BO - Output Latitude in DEGREES, always double precision OPTIONAL INPUT KEYWORD: /FK4 - If this keyword is set and non-zero, then input and output celestial and ecliptic coordinates should be given in equinox B1950. /RADIAN - if set, then all input and output angles are in radians rather than degrees. SELECT - The coordinate conversion integer (1-6) may alternatively be specified as a keyword EXAMPLE: Find the Galactic coordinates of Cyg X-1 (ra=299.590315, dec=35.201604) IDL> ra = 299.590315d IDL> dec = 35.201604d IDL> euler,ra,dec,glong,glat,1 & print,glong,glat 71.334990, 3.0668335 REVISION HISTORY: Written W. Landsman, February 1987 Adapted from Fortran by Daryl Yentis NRL Made J2000 the default, added /FK4 keyword W. Landsman December 1998 Add option to specify SELECT as a keyword W. Landsman March 2003 Use less virtual memory for large input arrays W. Landsman June 2008 Added /RADIAN input keyword W. Landsman Sep 2008
(See $IDLUTILS_DIR/goddard/pro/astro/euler.pro)
EXPAND_TILDE()
NAME: EXPAND_TILDE() PURPOSE: Expand tilde in UNIX directory names CALLING SEQUENCE: IDL> output=expand_tilde(input) INPUTS: INPUT = input file or directory name, scalar string OUTPUT: Returns expanded filename, scalar string EXAMPLES: output=expand_tilde('~zarro/test.doc') ---> output='/usr/users/zarro' NOTES: This version of EXPAND_TILDE differs from the version in the Solar Library in that it does not call the functions EXIST and IDL_RELEASE. However, it should work identically. PROCEDURE CALLS: None. REVISION HISTORY: Version 1, 17-Feb-1997, D M Zarro. Written Transfered from Solar Library W. Landsman Sep. 1997 Made more robust D. Zarro/W. Landsman Sep. 2000 Made even more robust (since things like ~zarro weren't being expanded) Zarro (EITI/GSFC, Mar 2001)
(See $IDLUTILS_DIR/goddard/pro/misc/expand_tilde.pro)
EXTAST
NAME: EXTAST PURPOSE: Extract ASTrometry parameters from a FITS image header. EXPLANATION: Extract World Coordinate System information ( http://fits.gsfc.nasa.gov/fits_wcs.html ) from a FITS header and place it into an IDL structure. CALLING SEQUENCE: EXTAST, hdr, [ astr, noparams, ALT= ] INPUT: HDR - variable containing the FITS header (string array) OUTPUTS: ASTR - Anonymous structure containing astrometry info from the FITS header ASTR always contains the following tags (even though some projections do not require all the parameters) .NAXIS - 2 element array giving image size .CD - 2 x 2 array containing the astrometry parameters CD1_1 CD1_2 in DEGREES/PIXEL CD2_1 CD2_2 .CDELT - 2 element double vector giving physical increment at the reference pixel .CRPIX - 2 element double vector giving X and Y coordinates of reference pixel (def = NAXIS/2) in FITS convention (first pixel is 1,1) .CRVAL - 2 element double precision vector giving R.A. and DEC of reference pixel in DEGREES .CTYPE - 2 element string vector giving projection types, default ['RA---TAN','DEC--TAN'] .LONGPOLE - scalar giving native longitude of the celestial pole (default = 180 for zenithal projections) .LATPOLE - scalar giving native latitude of the celestial pole default=0) .PV2 - Vector of projection parameter associated with latitude axis PV2 will have up to 21 elements for the ZPN projection, up to 3 for the SIN projection and no more than 2 for any other projection .DISTORT - optional substructure specifying any distortion parameters currently implemented only for "SIP" (Spitzer Imaging Polynomial) distortion parameters NOPARAMS - Scalar indicating the results of EXTAST -1 = Failure - Header missing astrometry parameters 1 = Success - Header contains CROTA + CDELT (AIPS-type) astrometry 2 = Success - Header contains CDn_m astrometry, rec. 3 = Success - Header contains PCn_m + CDELT astrometry. 4 = Success - Header contains ST Guide Star Survey astrometry (see gsssextast.pro ) OPTIONAL INPUT/OUTPUT KEYWORDS: ALT - single character 'A' through 'Z' or ' ' specifying an alternate astrometry system present in the FITS header. The default is to use the primary astrometry or ALT = ' '. If /ALT is set, then this is equivalent to ALT = 'A'. See Section 3.3 of Greisen & Calabretta (2002, A&A, 395, 1061) for information about alternate astrometry keywords. If not set on input, then ALT is set to ' ' on output. PROCEDURE: EXTAST checks for astrometry parameters in the following order: (1) the CD matrix PC1_1,PC1_2...plus CDELT*, CRPIX and CRVAL (2) the CD matrix CD1_1,CD1_2... plus CRPIX and CRVAL. (3) CROTA2 (or CROTA1) and CDELT plus CRPIX and CRVAL. All three forms are valid FITS according to the paper "Representations of World Coordinates in FITS by Greisen and Calabretta (2002, A&A, 395, 1061 http://fits.gsfc.nasa.gov/fits_wcs.html ) although form (1) is preferred. NOTES: 1. An anonymous structure is created to avoid structure definition conflicts. This is needed because some projection systems require additional dimensions (i.e. spherical cube projections require a specification of the cube face). 2, Some FITS headers (e.g.from HST/ACS) include SIP forward distortion coefficients but do not include the reverse coefficients. Currently, EXTAST only gives a warning that the reverse coefficients (RA,Dec to X,Y) are not present. EXTAST should actually compute the inverse coefficients, but this is not yet implemented.. PROCEDURES CALLED: GSSSEXTAST, ZPARCHECK REVISION HISTORY Written by B. Boothman 4/15/86 Accept CD001001 keywords 1-3-88 Accept CD1_1, CD2_1... keywords W. Landsman Nov. 92 Recognize GSSS FITS header W. Landsman June 94 Get correct sign, when converting CDELT* to CD matrix for right-handed coordinate system W. Landsman November 1998 Consistent conversion between CROTA and CD matrix October 2000 CTYPE = 'PIXEL' means no astrometry params W. Landsman January 2001 Don't choke if only 1 CTYPE value given W. Landsman August 2001 Recognize PC00n00m keywords again (sigh...) W. Landsman December 2001 Recognize GSSS in ctype also D. Finkbeiner Jan 2002 Introduce ALT keyword W. Landsman June 2003 Fix error introduced June 2003 where free-format values would be truncated if more than 20 characters. W. Landsman Aug 2003 Further fix to free-format values -- slash need not be present Sep 2003 Default value of LATPOLE is 90.0 W. Landsman February 2004 Allow for distortion substructure, currently implemented only for SIP (Spitzer Imaging Polynomial) W. Landsman February 2004 Correct LONGPOLE computation if CTYPE = ['*DEC','*RA'] W. L. Feb. 2004 Assume since V5.3 (vector STRMID) W. Landsman Feb 2004 Yet another fix to free-format values W. Landsman April 2004 Introduce PV2 tag to replace PROJP1, PROJP2.. etc. W. Landsman May 2004 Convert NCP projection to generalized SIN W. Landsman Aug 2004 Add NAXIS tag to output structure W. Landsman Jan 2007 .CRPIX tag now Double instead of Float W. Landsman Apr 2007 If duplicate keywords use the *last* value W. Landsman Aug 2008 Fix typo for AZP projection, nonzero longpole N. Cunningham Feb 2009 Give warning if reverse SIP coefficient not present W. Landsman Nov 2011 Allow obsolete CD matrix representations W. Landsman May 2012
(See $IDLUTILS_DIR/goddard/pro/astrom/extast.pro)
EXTGRP
NAME: EXTGRP PURPOSE: Extract the group parameter information out of SXREAD output EXPLANATION: This procedure extracts the group parameter information out of a header and parameter variable obtained from SXREAD. This allows astrometry, photometry and other parameters to be easily SXPARed by conventional methods and allows the image and header to be saved in a SIMPLE format. CALLING SEQUENCE: ExtGrp, hdr, par INPUT: HDR - The header which is to be converted (input and output) PAR - The Parameter string returned from a call to SXREAD OUTPUT: HDR - The converted header, string array OTHER PROCEDURES CALLED: SXPAR(), SXADDPAR, SXGPAR(), STRN() HISTORY: 25-JUN-90 Version 1 written 13-JUL-92 Header finally added to this ancient procedure, code spiffed up a bit. Now 3 times faster. Added PTYPE comment inclusion. E. Deutsch Converted to IDL V5.0 W. Landsman September 1997
(See $IDLUTILS_DIR/goddard/pro/sdas/extgrp.pro)
EXTRAP
NAME: EXTRAP PURPOSE: This procedure fills in the ends of a one-dimensional array from interior portions using polynomial extrapolation. CATEGORY: Image processing CALLING SEQUENCE: EXTRAP, Deg, X, Y, Y2 INPUT POSITIONAL PARAMETERS: Deg: Degree of polynomial X: Independent variable Y: Dependent variable KEYWORD PARAMETERS: LIMS: 3-element array giving range of X to be used to fit polynomial and starting point where extrapolation is to be substituted; if not given, you click on a plot; order of elements is [xmin, xmax, xstart]; if LIMS is specified, then program is silent OUTPUT POSITIONAL PARAMETERS: Y2: Dependent variable with extrapolated portion filled in SIDE EFFECTS: May pop a window for selecting range. MODIFICATION HISTORY: Written by RSH, RITSS, 14 Aug 98 Spiffed up for library. RSH, 6 Oct 98
(See $IDLUTILS_DIR/goddard/pro/image/skyadj_cube.pro)
FACTOR
NAME: FACTOR PURPOSE: Find prime factors of a given number. CATEGORY: CALLING SEQUENCE: factor, x, p, n INPUTS: x = Number to factor (>1). in KEYWORD PARAMETERS: Keywords: /QUIET means do not print factors. /DEBUG Means list steps as they happen. /TRY Go beyond 20000 primes. OUTPUTS: p = Array of prime numbers. out n = Count of each element of p. out COMMON BLOCKS: NOTES: Note: see also prime, numfactors, print_fact. MODIFICATION HISTORY: R. Sterner. 4 Oct, 1988. RES 25 Oct, 1990 --- converted to IDL V2. R. Sterner, 1999 Jun 30 --- Improved (faster, bigger). R. Sterner, 1999 Jul 7 --- Bigger values (used unsigned). R. Sterner, 1999 Jul 9 --- Tried to make backward compatable. R. Sterner, 2000 Jan 06 --- Fixed to ignore non-positive numbers. Johns Hopkins University Applied Physics Laboratory. Copyright (C) 1988, 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.
(See $IDLUTILS_DIR/goddard/pro/jhuapl/factor.pro)
FDECOMP
NAME: FDECOMP PURPOSE: Routine to decompose file name(s) for any operating system. CALLING SEQUENCE: FDECOMP, filename, disk, dir, name, qual, [OSFamily = ] INPUT: filename - string file name(s), scalar or vector OUTPUTS: All the output parameters will have the same number of elements as input filename disk - disk name, always '' on a Unix machine, scalar or vector string dir - directory name, scalar or vector string name - file name, scalar or vector string qual - qualifier, set equal to the characters beyond the last "." OPTIONAL INPUT KEYWORD: OSFamily - scalar string specifying the operating system, must be either 'Windows' or 'unix'. If not supplied, then !VERSION.OS_FAMILY is used to determine the OS. EXAMPLES: Consider the following file names unix: file = '/itt/idl71/avg.pro' Windows: file = 'd:\itt\idl71\avg.pro' then IDL> FDECOMP, file, disk, dir, name, qual will return the following Disk Dir Name Qual Unix: '' '/itt/idl71/' 'avg' 'pro' Windows: 'd:' \itt\idl71\ 'avg' 'pro' NOTES: (1) The period is removed between the name and qualifier (2) Unlike the intrinsic FILE_BASENAME() and FILE_DIRNAME() functions, one can use FDECOMP to decompose a Windows file name on a Unix machine or a Unix filename on a Windows machine. ROUTINES CALLED: None. HISTORY version 1 D. Lindler Oct 1986 Include VMS DECNET machine name in disk W. Landsman HSTX Feb. 94 Converted to Mac IDL, I. Freedman HSTX March 1994 Major rewrite to accept vector filenames V5.3 W. Landsman June 2000 Fix cases where disk name not always present W. Landsman Sep. 2000 Make sure version defined for Windows W. Landsman April 2004 Include final delimiter in directory under Windows as advertised W. Landsman May 2006 Remove VMS support, W. Landsman September 2006 Remove MacOS branch (same as Unix) W. Landsman August 2009
(See $IDLUTILS_DIR/goddard/pro/misc/fdecomp.pro)
FILTER_IMAGE
NAME: FILTER_IMAGE PURPOSE: Identical to MEDIAN or SMOOTH but handle edges and allow iterations. EXPLANATION: Computes the average and/or median of pixels in moving box, replacing center pixel with the computed average and/or median, (using the IDL SMOOTH() or MEDIAN() functions). The main reason for using this function is the options to also process the pixels at edges and corners of image, and, to apply iterative smoothing simulating convolution with Gaussian, and/or to convolve image with a Gaussian kernel. Users might also look at the function ESTIMATOR_FILTER() introduced in IDL 7.1. CALLING SEQUENCE: Result = filter_image( image, SMOOTH=width, MEDIAN = width, /ALL_PIXELS /ITERATE, FWHM =, /NO_FT_CONVOL) INPUT: image = 2-D array (matrix) OPTIONAL INPUT KEYWORDS: SMOOTH = scalar (odd) integer specifying the width of a square box for moving average, in # pixels. /SMOOTH means use box width = 3 pixels for smoothing. MEDIAN = scalar (usually odd) integer specifying the width of square moving box for median filter, in # pixels. /MEDIAN means use box width = 3 pixels for median filter. /ALL_PIXELS causes the edges of image to be filtered as well. This is accomplished by reflecting pixels adjacent to edges outward (similar to the /EDGE_WRAP keyword in CONVOL). Note that this is a different algorithm from the /EDGE_TRUNCATE keyword to SMOOTH or CONVOL, which duplicates the nearest pixel. /ITERATE means apply smooth(image,3) iteratively for a count of (box_width-1)/2 times (=radius), when box_width >= 5. This is equivalent to convolution with a Gaussian PSF of FWHM = 2 * sqrt( radius ) as radius gets large. Note that /ALL_PIXELS is automatically applied, giving better results in the iteration limit. (also, MEDIAN keyword is ignored when /ITER is specified). FWHM_GAUSSIAN = Full-width half-max of Gaussian to convolve with image. FWHM can be a single number (circular beam), or 2 numbers giving axes of elliptical beam. /NO_FT_CONVOL causes the convolution to be computed directly, with intrinsic IDL CONVOL function. The default is to use FFT when factors of size are all LE 13. Note that external function convolve.pro handles both cases) OPTIONAL INPUT/OUTPUT KEYWORD: PSF = Array containing the PSF used during the convolution. This keyword is only active if the FWHM_GAUSSIAN keyword is also specified. If PSF is undefined on input, then upon output it contains the Gaussian convolution specified by the FWHM_GAUSSIAN keyword. If the PSF array is defined on input then it is used as the convolution kernel, the value of the FWHM_GAUSSIAN keyword is ignored. Typically, on a first call set PSF to an undefined variable, which can be reused for subsequent calls to prevent recalculation of the Gaussian PSF. RESULT: Function returns the smoothed, median filtered, or convolved image. If both SMOOTH and MEDIAN are specified, median filter is applied first. If only SMOOTH is applied, then output is of same type as input. If either MEDIAN or FWHM_GAUSSIAN is supplied than the output is at least floating (double if the input image is double). EXAMPLES: To apply 3x3 moving median filter and then 3x3 moving average, both applied to all pixels: Result = filter_image( image, /SMOOTH, /MEDIAN, /ALL ) To iteratively apply 3x3 moving average filter for 4 = (9-1)/2 times, thus approximating convolution with Gaussian of FWHM = 2*sqrt(4) = 4 : Result = filter_image( image, SMOOTH=9, /ITER ) To convolve all pixels with Gaussian of FWHM = 3.7 x 5.2 pixels: Result = filter_image( image, FWHM=[3.7,5.2], /ALL ) EXTERNAL CALLS: function psf_gaussian function convolve pro factor function prime ;all these called only if FWHM is specified PROCEDURE: If both /ALL_PIXELS (or /ITERATE) keywords are set then create a larger image by reflecting the edges outward, then call the IDL MEDIAN() or SMOOTH() function on the larger image, and just return the central part (the original size image). NAN values are recognized during calls to MEDIAN() or SMOOTH(), but not for convolution with a Gaussian (FWHM keyword supplied). HISTORY: Written, 1991, Frank Varosi, NASA/GSFC. FV, 1992, added /ITERATE option. FV, 1993, added FWHM_GAUSSIAN= option. Use /EVEN call to median, recognize NAN values in SMOOTH W. Landsman June 2001 Added PSF keyword, Bjorn Heijligers/WL, September 2001 Keep same output data type if /ALL_PIXELS supplied A. Steffl Mar 2011
(See $IDLUTILS_DIR/goddard/pro/image/filter_image.pro)
FIND
NAME: FIND PURPOSE: Find positive brightness perturbations (i.e stars) in an image EXPLANATION: Also returns centroids and shape parameters (roundness & sharpness). Adapted from 1991 version of DAOPHOT, but does not allow for bad pixels and uses a slightly different centroid algorithm. Modified in March 2008 to use marginal Gaussian fits to find centroids CALLING SEQUENCE: FIND, image, [ x, y, flux, sharp, round, hmin, fwhm, roundlim, sharplim PRINT= , /SILENT, /MONITOR] INPUTS: image - 2 dimensional image array (integer or real) for which one wishes to identify the stars present OPTIONAL INPUTS: FIND will prompt for these parameters if not supplied hmin - Threshold intensity for a point source - should generally be 3 or 4 sigma above background RMS fwhm - FWHM (in pixels) to be used in the convolve filter sharplim - 2 element vector giving low and high cutoff for the sharpness statistic (Default: [0.2,1.0] ). Change this default only if the stars have significantly larger or or smaller concentration than a Gaussian roundlim - 2 element vector giving low and high cutoff for the roundness statistic (Default: [-1.0,1.0] ). Change this default only if the stars are significantly elongated. OPTIONAL INPUT KEYWORDS: /MONITOR - Normally, FIND will display the results for each star only if no output variables are supplied. Set /MONITOR to always see the result of each individual star. /SILENT - set /SILENT keyword to suppress all output display PRINT - if set and non-zero then FIND will also write its results to a file find.prt. Also one can specify a different output file name by setting PRINT = 'filename'. OPTIONAL OUTPUTS: x - vector containing x position of all stars identified by FIND y- vector containing y position of all stars identified by FIND flux - vector containing flux of identified stars as determined by a Gaussian fit. Fluxes are NOT converted to magnitudes. sharp - vector containing sharpness statistic for identified stars round - vector containing roundness statistic for identified stars NOTES: (1) The sharpness statistic compares the central pixel to the mean of the surrounding pixels. If this difference is greater than the originally estimated height of the Gaussian or less than 0.2 the height of the Gaussian (for the default values of SHARPLIM) then the star will be rejected. (2) More recent versions of FIND in DAOPHOT allow the possibility of ignoring bad pixels. Unfortunately, to implement this in IDL would preclude the vectorization made possible with the CONVOL function and would run extremely slowly. (3) Modified in March 2008 to use marginal Gaussian distributions to compute centroid. (Formerly, find.pro determined centroids by locating where derivatives went to zero -- see cntrd.pro for this algorithm. This was the method used in very old (~1984) versions of DAOPHOT. ) As discussed in more detail in the comments to the code, the centroid computation here is the same as in IRAF DAOFIND but differs slightly from the current DAOPHOT. PROCEDURE CALLS: GETOPT() REVISION HISTORY: Written W. Landsman, STX February, 1987 ROUND now an internal function in V3.1 W. Landsman July 1993 Change variable name DERIV to DERIVAT W. Landsman Feb. 1996 Use /PRINT keyword instead of TEXTOUT W. Landsman May 1996 Changed loop indices to type LONG W. Landsman Aug. 1997 Replace DATATYPE() with size(/TNAME) W. Landsman Nov. 2001 Fix problem when PRINT= filename W. Landsman October 2002 Fix problems with >32767 stars D. Schlegel/W. Landsman Sep. 2004 Fix error message when no stars found S. Carey/W. Landsman Sep 2007 Rewrite centroid computation to use marginal Gaussians W. Landsman Mar 2008 Added Monitor keyword, /SILENT now suppresses all output W. Landsman Nov 2008 Work when threshold is negative (difference images) W. Landsman May 2010
(See $IDLUTILS_DIR/goddard/pro/idlphot/find.pro)
FINDPRO
NAME: FINDPRO PURPOSE: Find all locations of a procedure in the IDL !PATH EXPLANATION: FINDPRO searces for the procedure name (as a .pro or a .sav file) in all IDL libraries or directories given in the !PATH system variable. This differs from the intrinsic FILE_WHICH() function which only finds the first occurence of the procedure name. CALLING SEQUENCE: FINDPRO, [ Proc_Name, /NoPrint, DirList = , ProList = ] OPTIONAL INPUT: Proc_Name - Character string giving the name of the IDL procedure or function. Do not include the ".pro" extension. If Proc_Name is omitted, the program will prompt for PROC_NAME. "*" wildcards are permitted. OPTIONAL KEYWORD INPUT: /NoPrint - if set, then the file's path is not printed on the screen and absolutely no error messages are printed on the screen. If not set, then - since the MESSAGE routine is used - error messages will be printed but the printing of informational messages depends on the value of the !Quiet variable. OPTIONAL KEYWORD OUTPUTS: DirList - The directories in which the file is located are returned in the keyword as a string array. If the procedure is an intrinsic IDL procedure, then the value of DirList = ['INTRINSIC']. If the procedure is not found, the value of DirList = ['']. ProList - The list (full pathnames) of procedures found. Useful if you are looking for the name of a procedure using wildcards. The order of the names in DirList and ProList is identical to the order in which the procedure name appears in the !PATH PROCEDURE: The system variable !PATH is parsed using EXPAND_PATH into individual directories. FILE_SEARCH() is used to search the directories for the procedure name. If not found in !PATH, then the name is compared with the list of intrinsic IDL procedures given by the ROUTINE_INFO() function. EXAMPLE: (1) Find the procedure CURVEFIT. Assume for this example that the user also has a copy of the curvefit.pro procedure in her home directory on a Unix machine. IDL> findpro, 'curvefit', DIRLIST=DirList Procedure curvefit.pro found in directory /home/user/. Procedure curvefit.pro found in directory /home/idl/lib/userlib IDL> help, DirList DIRLIST STRING = Array(2) IDL> help, DirList[0], DirList[1] <Expression> STRING = '/home/user' <Expression> STRING = '/home/idl/lib/userlib' (2) Find all procedures in one's !path containing the characters "zoom" IDL> findpro,'*zoom*' RESTRICTIONS: User will be unable to find a path for a native IDL function or procedure, or for a FORTRAN or C routine added with CALL_EXTERNAL. Remember that Unix is case sensitive, and most procedures will be in lower case. PROCEDURES USED: FDECOMP -- Decompose file name REVISION HISTORY: Based on code extracted from the GETPRO procedure, J. Parker 1994 Use the intrinsic EXPAND_PATH function W. Landsman Nov. 1994 Use ROUTINE_NAMES() to check for intrinsic procs W. Landsman Jul 95 Added Macintosh, WINDOWS compatibility W. Landsman Sep. 95 Removed spurious first element in PROLIST W. Landsman March 1997 Don't include duplicate directories in !PATH WL May 1997 Use ROUTINE_INFO instead of undocumented ROUTINE_NAMES W.L. October 1998 Also check for save sets W. Landsman October 1999 Force lower case check for VMS W. Landsman January 2000 Only return .pro or .sav files in PROLIST W. Landsman January 2002 Force lower case check for .pro and .sav D. Swain September 2002 Use FILE_SEARCH() if V5.5 or later W. Landsman June 2006 Assume since V55, remove VMS support W. Landsman Sep. 2006 Assume since V6.0, use file_basename() W.Landsman Feb 2009
(See $IDLUTILS_DIR/goddard/pro/misc/findpro.pro)
FIND_ALL_DIR()
NAME: FIND_ALL_DIR() PURPOSE: Finds all directories under a specified directory. EXPLANATION: This routine finds all the directories in a directory tree when the root of the tree is specified. This provides the same functionality as having a directory with a plus in front of it in the environment variable IDL_PATH. CALLING SEQUENCE: Result = FIND_ALL_DIR( PATH ) PATHS = FIND_ALL_DIR('+mypath', /PATH_FORMAT) PATHS = FIND_ALL_DIR('+mypath1:+mypath2') INPUTS: PATH = The path specification for the top directory in the tree. Optionally this may begin with the '+' character but the action is the same unless the PLUS_REQUIRED keyword is set. One can also path a series of directories separated by the correct character ("," for VMS, ":" for Unix) OUTPUTS: The result of the function is a list of directories starting from the top directory passed and working downward from there. Normally, this will be a string array with one directory per array element, but if the PATH_FORMAT keyword is set, then a single string will be returned, in the correct format to be incorporated into !PATH. OPTIONAL INPUT KEYWORDS: PATH_FORMAT = If set, then a single string is returned, in the format of !PATH. PLUS_REQUIRED = If set, then a leading plus sign is required in order to expand out a directory tree. This is especially useful if the input is a series of directories, where some components should be expanded, but others shouldn't. RESET = Often FIND_ALL_DIR is used with logical names. It can be rather slow to search through these subdirectories. The /RESET keyword can be used to redefine an environment variable so that subsequent calls don't need to look for the subdirectories. To use /RESET, the PATH parameter must contain the name of a *single* environment variable. For example setenv,'FITS_DATA=+/datadisk/fits' dir = find_all_dir('FITS_DATA',/reset,/plus) The /RESET keyword is usually combined with /PLUS_REQUIRED. PROCEDURE CALLS: DEF_DIRLIST, FIND_WITH_DEF(), BREAK_PATH() RESTRICTIONS: PATH must point to a directory that actually exists. REVISION HISTORY: Version 11, Zarro (SM&A/GSFC), 23-March-00 Removed all calls to IS_DIR Version 12, William Thompson, GSFC, 02-Feb-2001 In Windows, use built-in expand_path if able. Version 13, William Thompson, GSFC, 23-Apr-2002 Follow logical links in Unix (Suggested by Pascal Saint-Hilaire) Version 14, Zarro (EER/GSFC), 26-Oct-2002 Saved/restored current directory to protect against often mysterious directory changes caused by spawning FIND in Unix Version 15, William Thompson, GSFC, 9-Feb-2004 Resolve environment variables in Windows. Version : Version 16 W. Landsman GSFC Sep 2006 Remove VMS support
(See $IDLUTILS_DIR/goddard/pro/misc/find_all_dir.pro)
FIND_WITH_DEF()
NAME: FIND_WITH_DEF() PURPOSE: Searches for files with a default path and extension. EXPLANATION: Finds files using default paths and extensions, Using this routine together with environment variables allows an OS-independent approach to finding files. CALLING SEQUENCE: Result = FIND_WITH_DEF( FILENAME, PATHS [, EXTENSIONS ] ) INPUTS: FILENAME = Name of file to be searched for. It may either be a complete filename, or the path or extension could be left off, in which case the routine will attempt to find the file using the default paths and extensions. PATHS = One or more default paths to use in the search in case FILENAME does not contain a path itself. The individual paths are separated by commas, although in UNIX, colons can also be used. In other words, PATHS has the same format as !PATH, except that commas can be used as a separator regardless of operating system. The current directory is always searched first, unless the keyword NOCURRENT is set. A leading $ can be used in any path to signal that what follows is an environmental variable, but the $ is not necessary. Environmental variables can themselves contain multiple paths. OPTIONAL INPUTS: EXTENSIONS = Scalar string giving one or more extensions to append to end of filename if the filename does not contain one (e.g. ".dat"). The period is optional. Multiple extensions can be separated by commas or colons. OUTPUTS: The result of the function is the name of the file if successful, or the null string if unsuccessful. OPTIONAL INPUT KEYWORDS: NOCURRENT = If set, then the current directory is not searched. RESET = The FIND_WITH_DEF routine supports paths which are preceeded with the plus sign to signal that all subdirectories should also be searched. Often this is used with logical names. It can be rather slow to search through these subdirectories. The /RESET keyword can be used to redefine an environment variable so that subsequent calls don't need to look for the subdirectories. To use /RESET, the PATHS parameter must contain the name of a *single* environment variable. For example setenv,'FITS_DATA=+/datadisk/fits' file = find_with_def('test.fits','FITS_DATA',/reset) EXAMPLE: FILENAME = '' READ, 'File to open: ', FILENAME FILE = FIND_WITH_DEF( FILENAME, 'SERTS_DATA', '.fix' ) IF FILE NE '' THEN ... PROCEDURE CALLS: BREAK_PATH(), FIND_ALL_DIR(), STR_SEP() REVISION HISTORY: Version 1, William Thompson, GSFC, 3 May 1993. Removed trailing / and : characters. Fixed bugs Allow for commas within values of logical names. Added keyword NOCURRENT. Changed to call BREAK_PATH Version 2, William Thompson, GSFC, 3 November 1994 Made EXTENSIONS optional. Version 3, William Thompson, GSFC, 30 April 1996 Call FIND_ALL_DIR to resolve any plus signs. Version 4, S.V. Haugan, UiO, 5 June 1996 Using OPENR,..,ERROR=ERROR to avoid an IDL 3.6 internal nesting error. Version 5, R.A. Schwartz, GSFC, 11 July 1996 Use SPEC_DIR to interpret PATH under VMS Version 6, William Thompson, GSFC, 5 August 1996 Took out call to SPEC_DIR (i.e., reverted to version 4). The use of SPEC_DIR was required to support logical names defined via SETLOG,/CONFINE. However, it conflicted with the ability to use logical names with multiple values. Removing the /CONFINE made it unnecessary to call SPEC_DIR in this routine. Version 7, William Thompson, GSFC, 6 August 1996 Added keyword RESET Converted to IDL V5.0 W. Landsman October 1997 Use STRTRIM instead of TRIM, W. Landsman November 1998 Use STRSPLIT instead of STR_SEP W. Landsman July 2002
(See $IDLUTILS_DIR/goddard/pro/misc/find_with_def.pro)
FITEXY
NAME: FITEXY PURPOSE: Best straight-line fit to data with errors in both coordinates EXPLANATION: Linear Least-squares approximation in one-dimension (y = a + b*x), when both x and y data have errors CALLING EXAMPLE: FITEXY, x, y, A, B, X_SIG= , Y_SIG= , [sigma_A_B, chi_sq, q, TOL=] INPUTS: x = array of values for independent variable. y = array of data values assumed to be linearly dependent on x. REQUIRED INPUT KEYWORDS: X_SIGMA = scalar or array specifying the standard deviation of x data. Y_SIGMA = scalar or array specifying the standard deviation of y data. OPTIONAL INPUT KEYWORD: TOLERANCE = desired accuracy of minimum & zero location, default=1.e-3. OUTPUTS: A_intercept = constant parameter result of linear fit, B_slope = slope parameter, so that: ( A_intercept + B_slope * x ) approximates the y data. OPTIONAL OUTPUT: sigma_A_B = two element array giving standard deviation of A_intercept and B_slope parameters, respectively. The standard deviations are not meaningful if (i) the fit is poor (see parameter q), or (ii) b is so large that the data are consistent with a vertical (infinite b) line. If the data are consistent with *all* values of b, then sigma_A_B = [1e33,e33] chi_sq = resulting minimum Chi-Square of Linear fit, scalar q - chi-sq probability, scalar (0-1) giving the probability that a correct model would give a value equal or larger than the observed chi squared. A small value of q indicates a poor fit, perhaps because the errors are underestimated. As discussed by Tremaine et al. (2002, ApJ, 574, 740) an underestimate of the errors (e.g. due to an intrinsic dispersion) can lead to a bias in the derived slope, and it may be worth enlarging the error bars to get a reduced chi_sq ~ 1 COMMON: common fitexy, communicates the data for computation of chi-square. PROCEDURE CALLS: CHISQ_FITEXY() ;Included in this file MINF_BRACKET, MINF_PARABOLIC, ZBRENT ;In IDL Astronomy Library MOMENT(), CHISQR_PDF() ;In standard IDL distribution PROCEDURE: From "Numerical Recipes" column by Press and Teukolsky: in "Computer in Physics", May, 1992 Vol.6 No.3 Also see the 2nd edition of the book "Numerical Recipes" by Press et al. In order to avoid problems with data sets where X and Y are of very different order of magnitude the data are normalized before the fitting process is started. The following normalization is used: xx = (x - xm) / xs and sigx = x_sigma / xs where xm = MEAN(x) and xs = STDDEV(x) yy = (y - ym) / ys and sigy = y_sigma / ys where ym = MEAN(y) and ys = STDDEV(y) MODIFICATION HISTORY: Written, Frank Varosi NASA/GSFC September 1992. Now returns q rather than 1-q W. Landsman December 1992 Use CHISQR_PDF, MOMENT instead of STDEV,CHI_SQR1 W. Landsman April 1998 Fixed typo for initial guess of slope, this error was nearly always insignificant W. Landsman March 2000 Normalize X,Y before calculation (from F. Holland) W. Landsman Nov 2006
(See $IDLUTILS_DIR/goddard/pro/math/fitexy.pro)
FITSDIR
NAME: FITSDIR PURPOSE: Display selected FITS keywords from the headers of FITS files. EXPLANATION: The values of either user-specified or default FITS keywords are displayed in either the primary header and/or the first extension header. Unless the /NOSIZE keyword is set, the data size is also displayed. The default keywords are as follows (with keywords in 2nd row used if those in the first row not found, and the 3rd row if neither the keywords in the first or second rows found:) DATE-OBS TELESCOP OBJECT EXPTIME TDATEOBS TELNAME TARGNAME INTEG ;First Alternative DATE OBSERVAT EXPOSURE ;Second Alternative INSTRUME EXPTIM ;Third Alternative FITSDIR will also recognize gzip compressed files (must have a .gz or FTZ extension). CALLING SEQUENCE: FITSDIR , [ directory, TEXTOUT =, EXTEN=, KEYWORDS=, /NOSIZE, /NoTELESCOPE ALT1_KEYWORDS= ,ALT2_KEYWORDS = ,ALT3_KEYWORDS = OPTIONAL INPUT PARAMETERS: DIRECTORY - Scalar string giving file name, disk or directory to be searched. Wildcard file names are allowed. Examples of valid names include 'iraf/*.fits' (Unix), d:\myfiles\f*.fits', (Windows) or 'Macintosh HD:Files:*c0f.fits' (Macintosh). OPTIONAL KEYWORD INPUT PARAMETER KEYWORDS - FITS keywords to display, as either a vector of strings or as a comma delimited scalar string, e.g.'testname,dewar,filter' If not supplied, then the default keywords are 'DATE-OBS', 'TELESCOP','OBJECT','EXPTIME' ALT1_KEYWORDS - A list (either a vector of strings or a comma delimited strings of alternative keywords to use if the default KEYWORDS cannot be found. By default, 'TDATEOBS', is the alternative to DATE-OBS, 'TELNAME' for 'TELESCOP','TARGNAME' for 'OBJECT', and 'INTEG' for EXPTIME ALT2_KEYWORDS - A list (either a vector of strings or a comma delimited strings of alternative keywords to use if neither KEYWORDS nor ALT1_KEYWORDS can be found. ALT3_KEYWORDS - A list (either a vector of strings or a comma delimited strings of alternative keywords to use if neither KEYWORDS nor ALT1_KEYWORDS nor ALT2_KEYWORDS can be found. /NOSIZE - if set then information about the image size is not displayed TEXTOUT - Controls output device as described in TEXTOPEN procedure textout=1 TERMINAL using /more option textout=2 TERMINAL without /more option textout=3 <program>.prt textout=4 laser.tmp textout=5 user must open file textout=7 Append to existing <program>.prt file textout = filename (default extension of .prt) EXTEN - Specifies an extension number (/EXTEN works for first extension) which is checked for the desired keywords. /NOTELESCOPE - If set, then if the default keywords are used, then the TELESCOPE (or TELNAME, OBSERVAT, INSTRUME) keywords are omitted to give more room for display other keywords. The /NOTELESCOP keyword has no effect if the default keywords are not used. OUTPUT PARAMETERS: None. EXAMPLES: (1) Print info on all'*.fits' files in the current directory using default keywords. Include information from the extension header IDL> fitsdir,/exten (2) Write a driver program to display selected keywords in HST/ACS drizzled (*drz) images pro acsdir keywords = 'date-obs,targname,detector,filter1,filter2,exptime' fitsdir,'*drz.fits',key=keywords,/exten return & end (3) Write info on all *.fits files in the Unix directory /usr2/smith, to a file 'smith.txt' using the default keywords, but don't display the value of the TELESCOPE keyword IDL> fitsdir ,'/usr2/smith/*.fits',t='smith.txt', /NoTel PROCEDURE: FILE_SEARCH() is used to find the specified FITS files. The header of each file is read, and the selected keywords are extracted. The formatting is adjusted so that no value is truncated on display. SYSTEM VARIABLES: TEXTOPEN (called by FITSDIR) will automatically define the following non-standard system variables if they are not previously defined: DEFSYSV,'!TEXTOUT',1 DEFSYSV,'!TEXTUNIT',0 PROCEDURES USED: FDECOMP, FXMOVE, MRD_HREAD, REMCHAR TEXTOPEN, TEXTCLOSE MODIFICATION HISTORY: Written, W. Landsman, HSTX February, 1993 Search alternate keyword names W.Landsman October 1998 Avoid integer truncation for NAXISi >32767 W. Landsman July 2000 Don't leave open unit W. Landsman July 2000 Added EXTEN keyword, work with compressed files, additional alternate keywords W. Landsman December 2000 Don't assume floating pt. exposure time W. Landsman September 2001 Major rewrite, KEYWORD & ALT*_KEYWORDS keywords, no truncation, /NOSIZE keyword W. Landsman, SSAI August 2002 Assume V5.3 or later W. Landsman November 2002 Fix case where no keywords supplied W. Landsman January 2003 NAXIS* values must be integers W. Landsman SSAI June 2003 Trim spaces off of input KEYWORD values W. Landsman March 2004 Treat .FTZ extension as gzip compressed W. Landsman September 2004 Assume since V5.5, file_search() available W. Landsman Aug 2006 Don't assume all images compressed or uncompressed W. L. Apr 2010 Use V6.0 notation W.L. Feb 2011
(See $IDLUTILS_DIR/goddard/pro/fits/fitsdir.pro)
FITSRGB_TO_TIFF
NAME: FITSRGB_to_TIFF PURPOSE: Combine separate red, green, and blue FITS images into TIFF format EXPLANATION: The output TIFF (class R) file can have colors interleaved either by pixel or image. The colour mix is also adjustable. CALLING SEQUENCE: FITSRGB_to_TIFF, path, rgb_files, tiff_name [,/BY_PIXEL, /PREVIEW, RED= , GREEN =, BLUE =] INPUTS: path = file system directory path to the RGB files required. rgb_files = string array with three components - the red FITS file filename, the blue FITS file filename and the green FITS file filename OUTPUTS: tiff_name = string containing name of tiff file to be produced OPTIONAL OUTPUT: Header = String array containing the header from the FITS file. OPTIONAL INPUT KEYWORDS: BY_PIXEL = This causes TIFF file RGB to be interleaved by pixel rather than the default of by image. PREVIEW = Allows a 24 bit image to be displayed on the screen to check the colour mix. RED = Real number containing the fractional mix of red GREEN = Real number containing the fractional mix of green BLUE = Real number containing the fractional mix of blue EXAMPLE: Read three FITS files, 'red.fits', 'blue.fits' and 'green.fits' from the directory '/data/images/space' and output a TIFF file named 'colour.tiff' IDL> FITSRGB_to_TIFF, '/data/images/space', ['red.fits', $ 'blue.fits', 'green.fits'], 'colour.tiff' Read three FITS files, 'red.fits', 'blue.fits' and 'green.fits' from the current directory and output a TIFF file named '/images/out.tiff' In this case, the red image is twice as strong as the green and the blue is a third more intense. A preview on screen is also wanted. IDL> FITSRGB_to_TIFF, '.', ['red.fits', $ 'blue.fits', 'green.fits'], '/images/out.tiff', $ /PREVIEW, RED=0.5, GREEN=1.0, BLUE=0.666 RESTRICTIONS: (1) Limited to the ability of the routine READFITS NOTES: None PROCEDURES USED: Functions: READFITS, CONCAT_DIR Procedures: WRITE_TIFF MODIFICATION HISTORY: 16th January 1995 - Written by Carl Shaw, Queen's University Belfast 27 Jan 1995 - W. Landsman, Add CONCAT_DIR for VMS, Windows compatibility Converted to IDL V5.0 W. Landsman September 1997 Use WRITE_TIFF instead of obsolete TIFF_WRITE W. Landsman December 1998 Cosmetic changes W. Landsman February 2000
(See $IDLUTILS_DIR/goddard/pro/fits/fitsrgb_to_tiff.pro)
FITS_ADD_CHECKSUM
NAME: FITS_ADD_CHECKSUM PURPOSE: Add or update the CHECKSUM and DATASUM keywords in a FITS header EXPLANATION: Follows the 23 May 2002 version of the FITS checksum proposal at http://heasarc.gsfc.nasa.gov/docs/heasarc/fits/checksum.html CALLING SEQUENCE: FITS_ADD_CHECKSUM, Hdr, [ Data, /No_TIMESTAMP, /FROM_IEEE ] INPUT-OUTPUT: Hdr - FITS header (string array), it will be updated with new (or modfied) CHECKSUM and DATASUM keywords OPTIONAL INPUT: Data - data array associated with the FITS header. If not supplied, or set to a scalar, then the program checks whether there is a DATASUM keyword already in the FITS header containing the 32bit checksum for the data. if there is no such keyword then there assumed to be no data array associated with the FITS header. OPTIONAL INPUT KEYWORDS: /FROM_IEEE - If this keyword is set, then the input is assumed to be in big endian format (e.g. an untranslated FITS array). This keyword only has an effect on little endian machines (e.g. a Linux box). /No_TIMESTAMP - If set, then a time stamp is not included in the comment field of the CHECKSUM and DATASUM keywords. Unless the /No_TIMESTAMP keyword is set, repeated calls to FITS_ADD_CHECKSUM with the same header and data will yield different values of CHECKSUM (as the date stamp always changes). However, use of the date stamp is recommended in the checksum proposal. PROCEDURES USED: CHECKSUM32, FITS_ASCII_ENCODE(), GET_DATE, SXADDPAR, SXPAR() REVISION HISTORY: W. Landsman SSAI December 2002 Fix problem with images with a multiple of 2880 bytes. W.L. May 2008 Avoid conversion error when DATASUM is an empty string W.L. June 2008 Don't update DATASUM if not already present and no data array supplied W.L. July 2008 Make sure input header array has 80 chars/line W.L. Aug 2009
(See $IDLUTILS_DIR/goddard/pro/fits/fits_add_checksum.pro)
FITS_ASCII_ENCODE()
NAME: FITS_ASCII_ENCODE() PURPOSE: Encode an unsigned longword as an ASCII string to insert in a FITS header EXPLANATION: Follows the 23 May 2002 version of the FITS checksum proposal at http://heasarc.gsfc.nasa.gov/docs/heasarc/fits/checksum.html CALLING SEQUENCE: result = FITS_ASCII_ENCODE( sum32) INPUTS: sum32 - 32bit *unsigned longword* (e.g. as returned by CHECKSUM32) RESULT: A 16 character scalar string suitable for the CHECKSUM keyword EXAMPLE: A FITS header/data unit has a checksum of 868229149. Encode the complement of this value (3426738146) into an ASCII string IDL> print,FITS_ASCII_ENCODE(3426738146U) ===> "hcHjjc9ghcEghc9g" METHOD: The 32bit value is interpreted as a sequence of 4 unsigned 8 bit integers, and divided by 4. Add an offset of 48b (ASCII '0'). Remove non-alphanumeric ASCII characters (byte values 58-64 and 91-96) by simultaneously incrementing and decrementing the values in pairs. Cyclicly shift the string one place to the right. REVISION HISTORY: Written W. Landsman SSAI December 2002
(See $IDLUTILS_DIR/goddard/pro/fits/fits_ascii_encode.pro)
FITS_CD_FIX
NAME: FITS_CD_FIX PURPOSE: Update obsolete representations of the CD matrix in a FITS header EXPLANATION: According the paper, "Representations of Celestial Coordinates in FITS" by Calabretta & Greisen (2002, A&A, 395, 1077, available at http://fits.gsfc.nasa.gov/fits_wcs.html) the rotation of an image from standard coordinates is represented by a coordinate description (CD) matrix. The standard representation of the CD matrix are PCn_m keywords, but CDn_m keywords (which include the scale factors) are also allowed. However, earliers drafts of the standard allowed the keywords forms CD00n00m and PC00n00m. This procedure will convert FITS CD matrix keywords containing zeros into the standard forms CDn_m and PCn_m containing only underscores. CALLING SEQUENCE: FITS_CD_FIX, Hdr INPUT-OUTPUT: HDR - FITS header, 80 x N string array. If the header does not contain 'CD00n00m' or 'PC00n00m' keywords then it is left unmodified. Otherwise, the keywords containing integers are replaced with those containing underscores. OPTIONAL KEYWORD INPUT /REVERSE - this keyword does nothing, but is kept for compatibility with earlier versions. PROCEDURES USED: SXADDPAR, SXDELPAR, SXPAR() REVISION HISTORY: Written W. Landsman Feb 1990 Major rewrite Feb 1994 Converted to IDL V5.0 W. Landsman September 1997 Use double precision formatting of CD matrix W. Landsman April 2000 Major rewrite to convert only to forms recognized by the Greisen & Calabretta standard W. Landsman July 2003
(See $IDLUTILS_DIR/goddard/pro/astrom/fits_cd_fix.pro)
FITS_CLOSE
NAME: FITS_CLOSE *PURPOSE: Close a FITS data file *CATEGORY: INPUT/OUTPUT *CALLING SEQUENCE: FITS_CLOSE,fcb *INPUTS: FCB: FITS control block returned by FITS_OPEN. *KEYWORD PARAMETERS: /NO_ABORT: Set to return to calling program instead of a RETALL when an I/O error is encountered. If set, the routine will return a non-null string (containing the error message) in the keyword MESSAGE. If /NO_ABORT not set, then FITS_CLOSE will print the message and issue a RETALL MESSAGE = value: Output error message *EXAMPLES: Open a FITS file, read some data, and close it with FITS_CLOSE FITS_OPEN,'infile',fcb FITS_READ,fcb,data FITS_READ,fcb,moredata FITS_CLOSE,fcb *HISTORY: Written by: D. Lindler August, 1995 Converted to IDL V5.0 W. Landsman September 1997 Do nothing if fcb an invalid structure D. Schlegel/W. Landsman Oct. 2000 Return Message='' for to signal normal operation W. Landsman Nov. 2000
(See $IDLUTILS_DIR/goddard/pro/fits/fits_close.pro)
FITS_HELP
NAME: FITS_HELP PURPOSE: To print a summary of the primary data units and extensions in a FITS file. ; CALLING SEQUENCE: FITS_HELP,filename_or_fcb INPUTS: FILENAME_OR_FCB - name of the fits file or the FITS Control Block (FCB) structure returned by FITS_OPEN. The file name is allowed to be gzip compressed (with a .gz extension) OUTPUTS: A summary of the FITS file is printed. For each extension, the values of the XTENSION, EXTNAME EXTVER EXTLEVEL BITPIX GCOUNT, PCOUNT NAXIS and NAXIS* keywords are displayed. EXAMPLES: FITS_HELP,'myfile.fits' FITS_OPEN,'anotherfile.fits',fcb FITS_HELP,fcb PROCEDURES USED: FITS_OPEN, FITS_CLOSE HISTORY: Written by: D. Lindler August, 1995 Converted to IDL V5.0 W. Landsman September 1997 Don't truncate EXTNAME values at 10 chars W. Landsman Feb. 2005 Use V6.0 notation W. Landsman Jan 2012
(See $IDLUTILS_DIR/goddard/pro/fits/fits_help.pro)
FITS_INFO
NAME: FITS_INFO PURPOSE: Provide information about the contents of a FITS file EXPLANATION: Information includes number of header records and size of data array. Applies to primary header and all extensions. Information can be printed at the terminal and/or stored in a common block This routine is mostly obsolete, and better results can be usually be performed with FITS_HELP (for display) or FITS_OPEN (to read FITS information into a structure) CALLING SEQUENCE: FITS_INFO, Filename, [ /SILENT , TEXTOUT = , N_ext =, EXTNAME= ] INPUT: Filename - Scalar string giving the name of the FITS file(s) Can include wildcards such as '*.fits', or regular expressions allowed by the FILE_SEARCH() function. One can also search gzip compressed FITS files, but their extension must end in .gz or .ftz. OPTIONAL INPUT KEYWORDS: /SILENT - If set, then the display of the file description on the terminal will be suppressed TEXTOUT - specifies output device. textout=1 TERMINAL using /more option textout=2 TERMINAL without /more option textout=3 <program>.prt textout=4 laser.tmp textout=5 user must open file, see TEXTOPEN textout=7 append to existing <program.prt> file textout = filename (default extension of .prt) If TEXTOUT is not supplied, then !TEXTOUT is used OPTIONAL OUTPUT KEYWORDS: N_ext - Returns an integer scalar giving the number of extensions in the FITS file extname - returns a list containing the EXTNAME keywords for each extension. COMMON BLOCKS DESCRIPTOR = File descriptor string of the form N_hdrrec Naxis IDL_type Naxis1 Naxis2 ... Naxisn [N_hdrrec table_type Naxis IDL_type Naxis1 ... Naxisn] (repeated for each extension) For example, the following descriptor 167 2 4 3839 4 55 BINTABLE 2 1 89 5 indicates that the primary header containing 167 lines, and the primary (2D) floating point image (IDL type 4) is of size 3839 x 4. The first extension header contains 55 lines, and the byte (IDL type 1) table array is of size 89 x 5. The DESCRIPTOR is *only* computed if /SILENT is set. EXAMPLE: Display info about all FITS files of the form '*.fit' in the current directory IDL> fits_info, '*.fit' Any time a *.fit file is found which is *not* in FITS format, an error message is displayed at the terminal and the program continues PROCEDURES USED: GETTOK(), MRD_SKIP, STRN(), SXPAR(), TEXTOPEN, TEXTCLOSE SYSTEM VARIABLES: The non-standard system variables !TEXTOUT and !TEXTUNIT will be created by FITS_INFO if they are not previously defined. DEFSYSV,'!TEXTOUT',1 DEFSYSV,'!TEXTUNIT',0 See TEXTOPEN.PRO for more info MODIFICATION HISTORY: Written, K. Venkatakrishna, Hughes STX, May 1992 Added N_ext keyword, and table_name info, G. Reichert Work on *very* large FITS files October 92 More checks to recognize corrupted FITS files February, 1993 Proper check for END keyword December 1994 Correctly size variable length binary tables WBL December 1994 EXTNAME keyword can be anywhere in extension header WBL January 1998 Correctly skip past extensions with no data WBL April 1998 Converted to IDL V5.0, W. Landsman, April 1998 No need for !TEXTOUT if /SILENT D.Finkbeiner February 2002 Define !TEXTOUT if needed. R. Sterner, 2002 Aug 27 Work on gzip compressed files for V5.3 or later W. Landsman 2003 Jan Improve speed by only reading first 36 lines of header Count headers with more than 32767 lines W. Landsman Feb. 2003 Assume since V5.3 (OPENR,/COMPRESS) W. Landsman Feb 2004 EXTNAME keyword can be anywhere in extension header again WBL/S. Bansal Dec 2004 Read more than 200 extensions WBL March 2005 Work for FITS files with SIMPLE=F WBL July 2005 Assume since V5.4, fstat.compress available WBL April 2006 Added EXTNAME as an IDL keyword to return values. M. Perrin Dec 2007 make Ndata a long64 to deal with large files. E. Hivon Mar 2008 For GDL compatibility, first check if file is compressed before using OPENR,/COMPRESS B. Roukema/WL Apr 2010
(See $IDLUTILS_DIR/goddard/pro/fits/fits_info.pro)
FITS_OPEN
NAME: FITS_OPEN PURPOSE: Opens a FITS (Flexible Image Transport System) data file. EXPLANATION: Used by FITS_READ and FITS_WRITE CALLING SEQUENCE: FITS_OPEN, filename, fcb INPUTS: filename : name of the FITS file to open, scalar string FITS_OPEN can also open gzip compressed (.gz) file *for reading only*, although there is a performance penalty FPACK ( http://heasarc.gsfc.nasa.gov/fitsio/fpack/ ) compressed FITS files can be read provided that the FPACK software is installed. *OUTPUTS: fcb : (FITS Control Block) a IDL structure containing information concerning the file. It is an input to FITS_READ, FITS_WRITE FITS_CLOSE and MODFITS. INPUT KEYWORD PARAMETERS: /APPEND: Set to append to an existing file. /FPACK - Signal that the file is compressed with the FPACK software. http://heasarc.gsfc.nasa.gov/fitsio/fpack/ ) By default, FITS_OPEN assumes that if the file name extension ends in .fz that it is fpack compressed. The FPACK software must be installed on the system /HPRINT - print headers with routine HPRINT as they are read. (useful for debugging a strange file) /NO_ABORT: Set to quietly return to calling program when an I/O error is encountered, and return a non-null string (containing the error message) in the keyword MESSAGE. If /NO_ABORT not set, then FITS_OPEN will display the error message and return to the calling program. /UPDATE Set this keyword to open an existing file for update /WRITE: Set this keyword to open a new file for writing. OUTPUT KEYWORD PARAMETERS: MESSAGE = value: Output error message. If the FITS file was opened successfully, then message = ''. NOTES: The output FCB should be passed to the other FITS routines (FITS_OPEN, FITS_READ, FITS_HELP, and FITS_WRITE). It has the following structure when FITS_OPEN is called without /WRITE or /APPEND keywords set. FCB.FILENAME - name of the input file .UNIT - unit number the file is opened to .FCOMPRESS - 1 if unit is a FPACK compressed file opened with a pipe to SPAWN .NEXTEND - number of extensions in the file. .XTENSION - string array giving the extension type for each extension. .EXTNAME - string array giving the extension name for each extension. (null string if not defined the extension) .EXTVER - vector of extension version numbers (0 if not defined) .EXTLEVEL - vector of extension levels (0 if not defined) .GCOUNT - vector with the number of groups in each extension. .PCOUNT - vector with parameter count for each group .BITPIX - BITPIX for each extension with values 8 byte data 16 short word integers 32 long word integers -32 IEEE floating point -64 IEEE double precision floating point .NAXIS - number of axes for each extension. (0 for null data units) .AXIS - 2-D array where axis(*,N) gives the size of each axes for extension N .START_HEADER - vector giving the starting byte in the file where each extension header begins .START_DATA - vector giving the starting byte in the file where the data for each extension begins .HMAIN - keyword parameters (less standard required FITS keywords) for the primary data unit. .OPEN_FOR_WRITE - flag (0= open for read, 1=open for write, 2=open for update) .LAST_EXTENSION - last extension number read. .RANDOM_GROUPS - 1 if the PDU is random groups format, 0 otherwise .NBYTES - total number of (uncompressed) bytes in the FITS file When FITS open is called with the /WRITE or /APPEND option, FCB contains: FCB.FILENAME - name of the input file .UNIT - unit number the file is opened to .NEXTEND - number of extensions in the file. .OPEN_FOR_WRITE - flag (1=open for write, 2=open for append 3=open for update) EXAMPLES: Open a FITS file for reading: FITS_OPEN,'myfile.fits',fcb Open a new FITS file for output: FITS_OPEN,'newfile.fits',fcb,/write PROCEDURES USED: GET_PIPE_FILESIZE (for Fcompress'ed files) HPRINT, SXDELPAR, SXPAR() HISTORY: Written by: D. Lindler August, 1995 July, 1996 NICMOS Modified to allow open for overwrite to allow primary header to be modified DJL Oct. 15, 1996 corrected to properly extend AXIS when more than 100 extensions present Converted to IDL V5.0 W. Landsman September 1997 Use Message = '' rather than !ERR =1 as preferred signal of normal operation W. Landsman November 2000 Lindler, Dec, 2001, Modified to use 64 bit words for storing byte positions within the file to allow support for very large files Work with gzip compressed files W. Landsman January 2003 Fix gzip compress for V5.4 and earlier W.Landsman/M.Fitzgerald Dec 2003 Assume since V5.3 (STRSPLIT, OPENR,/COMPRESS) W. Landsman Feb 2004 Treat FTZ extension as gzip compressed W. Landsman Sep 2004 Assume since V5.4 fstat.compress available W. Landsman Apr 2006 FCB.Filename now expands any wildcards W. Landsman July 2006 Make ndata 64bit for very large files B. Garwood/W. Landsman Sep 2006 Open with /SWAP_IF_LITTLE_ENDIAN, remove obsolete keywords to OPEN W. Landsman Sep 2006 Warn that one cannot open a compressed file for update W.L. April 2007 Use post-V6.0 notation W.L. October 2010 Support FPACK compressed files, new .FCOMPRESS tag to FCB structure W.L. December 2010
(See $IDLUTILS_DIR/goddard/pro/fits/fits_open.pro)
FITS_READ
NAME: FITS_READ PURPOSE: To read a FITS file. CALLING SEQUENCE: FITS_READ, filename_or_fcb, data [,header, group_par] INPUTS: FILENAME_OR_FCB - this parameter can be the FITS Control Block (FCB) returned by FITS_OPEN or the file name of the FITS file. If a file name is supplied, FITS_READ will open the file with FITS_OPEN and close the file with FITS_CLOSE before exiting. When multiple extensions are to be read from the file, it is more efficient for the user to call FITS_OPEN and leave the file open until all extensions are read. FPACK ( http://heasarc.gsfc.nasa.gov/fitsio/fpack/ ) compressed FITS files can be read provided that the FPACK software is installed. OUTPUTS: DATA - data array. If /NOSCALE is specified, BSCALE and BZERO (if present in the header) will not be used to scale the data. If Keywords FIRST and LAST are used to read a portion of the data or the heap portion of an extension, no scaling is done and data is returned as a 1-D vector. The user can use the IDL function REFORM to convert the data to the correct dimensions if desired. If /DATA_ONLY is specified, no scaling is done. HEADER - FITS Header. The STScI inheritance convention is recognized http://fits.gsfc.nasa.gov/registry/inherit/fits_inheritance.txt If an extension is read, and the INHERIT keyword exists with a value of T, and the /NO_PDU keyword keyword is not supplied, then the primary data unit header and the extension header will be combined. The header will have the form: <required keywords for the extension: XTENSION, BITPIX, NAXIS, ...> BEGIN MAIN HEADER -------------------------------- <PDU header keyword and history less required keywords: SIMPLE, BITPIX, NAXIS, ...> BEGIN EXTENSION HEADER --------------------------- <extension header less required keywords that were placed at the beginning of the header. END The structure of the header is such that if a keyword is duplicated in both the PDU and extension headers, routine SXPAR will print a warning and return the extension value of the keyword. GROUP_PAR - Group parameter block for FITS random groups format files or the heap area for variable length binary tables. Any scale factors in the header (PSCALn and PZEROn) are not applied to the group parameters. INPUT KEYWORD PARAMETERS: /NOSCALE: Set to return the FITS data without applying the scale factors BZERO and BSCALE. /HEADER_ONLY: set to read the header only. /DATA_ONLY: set to read the data only. If set, if any scale factors are present (BSCALE or BZERO), they will not be applied. /NO_PDU: By default, FITS_READ will add the primary data unit header keywords to the output header, *if* the header includes INHERIT = T. Set /NO_PDU to never append the primary header. /NO_ABORT: Set to return to calling program instead of a RETALL when an I/O error is encountered. If set, the routine will return a non-null string (containing the error message) in the keyword MESSAGE. (For backward compatibility, the obsolete system variable !ERR is also set to -1 in case of an error.) If /NO_ABORT not set, then FITS_READ will print the message and issue a RETALL /NO_UNSIGNED - By default, if the header indicates an unsigned integer (BITPIX = 16, BZERO=2^15, BSCALE=1) then FITS_READ will output an IDL unsigned integer data type (UINT). But if /NO_UNSIGNED is set, then the data is converted to type LONG. /PDU - If set, then always add the primary data unit header keywords to the output header, even if the INHERIT=T keyword is not found This was the default behavior of FITS_READ prior to April 2007 EXTEN_NO - extension number to read. If not set, the next extension in the file is read. Set to 0 to read the primary data unit. XTENSION - string name of the xtension to read EXTNAME - string name of the extname to read EXTVER - integer version number to read EXTLEVEL - integer extension level to read FIRST - set this keyword to only read a portion of the data. It gives the first word of the data to read LAST - set this keyword to only read a portion of the data. It gives the last word number of the data to read GROUP - group number to read for GCOUNT>1. (Default=0, the first group) OUTPUT KEYWORD PARAMETERS: ENUM - Output extension number that was read. MESSAGE = value: Output error message NOTES: Determination or which extension to read. case 1: EXTEN_NO specified. EXTEN_NO will give the number of the extension to read. The primary data unit is refered to as extension 0. If EXTEN_NO is specified, XTENSION, EXTNAME, EXTVER, and EXTLEVEL parameters are ignored. case 2: if EXTEN_NO is not specified, the first extension with the specified XTENSION, EXTNAME, EXTVER, and EXTLEVEL will be read. If any of the 4 parameters are not specified, they will not be used in the search. Setting EXTLEVEL=0, EXTVER=0, EXTNAME='', or XTENSION='' is the same as not supplying them. case 3: if none of the keyword parameters, EXTEN_NO, XTENSION, EXTNAME, EXTVER, or EXTLEVEL are supplied. FITS_READ will read the next extension in the file. If the primary data unit (PDU), extension 0, is null, the first call to FITS_READ will read the first extension of the file. The only way to read a null PDU is to use EXTEN_NO = 0. If FIRST and LAST are specified, the data is returned without applying any scale factors (BSCALE and BZERO) and the data is returned in a 1-D vector. This will allow you to read any portion of a multiple dimension data set. Once returned, the IDL function REFORM can be used to place the correct dimensions on the data. IMPLICIT IMAGES: FITS_READ will construct an implicit image for cases where NAXIS=0 and the NPIX1, NPIX2, and PIXVALUE keywords are present. The output image will be: image = replicate(PIXVALUE,NPIX1,NPIX2) FPACK compressed files are always closed and reopened when exiting FITS_READ so that the pointer is set to the beginning of the file. (Since FPACK files are opened with a bidirectional pipe rather than OPEN, one cannot use POINT_LUN to move to a specified position in the file.) EXAMPLES: Read the primary data unit of a FITS file, if it is null read the first extension: FITS_READ, 'myfile.fits', data, header Read the first two extensions of a FITS file and the extension with EXTNAME = 'FLUX' and EXTVER = 4 FITS_OPEN, 'myfile.fits', fcb FITS_READ, fcb,data1, header2, exten_no = 1 FITS_READ, fcb,data1, header2, exten_no = 2 FITS_READ, fcb,data3, header3, extname='flux', extver=4 FITS_CLOSE, fcb Read the sixth image in a data cube for the fourth extension. FITS_OPEN, 'myfile.fits', fcb image_number = 6 ns = fcb.axis(0,4) nl = fcb.axis(1,4) i1 = (ns*nl)*(image_number-1) i2 = i2 + ns*nl-1 FITS_READ,fcb,image,header,first=i1,last=i2 image = reform(image,ns,nl,/overwrite) FITS_CLOSE PROCEDURES USED: FITS_CLOSE, FITS_OPEN SXADDPAR, SXDELPAR, SXPAR() WARNINGS: In Sep 2006, FITS_OPEN was modified to open FITS files using the /SWAP_IF_LITTLE_ENDIAN keyword to OPEN, so that subsequent routines (FITS_READ, FITS_WRITE) did not require any byte swapping. An error may result if an pre-Sep 2006 version of FITS_OPEN is used with a post Sep 2006 version of FITS_READ, FITS_WRITE or MODFITS. HISTORY: Written by: D. Lindler, August 1995 Avoid use of !ERR W. Landsman August 1999 Read unsigned datatypes, added /no_unsigned W. Landsman December 1999 Don't call FITS_CLOSE unless fcb is defined W. Landsman January 2000 Set BZERO = 0 for unsigned integer data W. Landsman January 2000 Only call IEEE_TO_HOST if needed W. Landsman February 2000 Ensure EXTEND keyword in primary header W. Landsman April 2001 Don't erase ERROR message when closing file W. Landsman April 2002 Assume at least V5.1 remove NANValue keyword W. Landsman November 2002 Work with compress files (read file size from fcb), requires updated (Jan 2003) version of FITS_OPEN W. Landsman Jan 2003 Do not modify BSCALE/BZERO for unsigned integers W. Landsman April 2006 Asuume FITS_OPEN has opened the file with /SWAP_IF_LITTLE_ENDIAN W. Landsman September 2006 Fix problem with /DATA_ONLY keyword M.Buie/W.Landsman October 2006 Only append primary header if INHERIT=T W. Landsman April 2007 Make ndata 64bit for very large files E. Hivon/W. Landsman May 2007 Added /PDU keyword to always append primary header W. Landsman June 2007 Use PRODUCT to compute # of data points W. Landsman May 2009 Make sure FIRST is long64 when computing position W.L. October 2009 Read FPACK compressed files, W.L. December 2010
(See $IDLUTILS_DIR/goddard/pro/fits/fits_read.pro)
FITS_TEST_CHECKSUM()
NAME: FITS_TEST_CHECKSUM() PURPOSE: Verify the values of the CHECKSUM and DATASUM keywords in a FITS header EXPLANATION: Follows the 2007 version of the FITS checksum proposal at http://fits.gsfc.nasa.gov/registry/checksum.html CALLING SEQUENCE: result = FITS_TEST_CHECKSUM(HDR, [ DATA, ERRMSG=, /FROM_IEEE ]) INPUTS: HDR - FITS header (vector string) OPTIONAL DATA: DATA - data array associated with the FITS header. If not supplied, or set to a scalar, then there is assumed to be no data array associated with the FITS header. RESULT: An integer -1, 0 or 1 indicating the following conditions: 1 - CHECKSUM (and DATASUM) keywords are present with correct values 0 - CHECKSUM keyword is not present -1 - CHECKSUM or DATASUM keyword does not have the correct value indicating possible data corruption. OPTIONAL INPUT KEYWORD: /FROM_IEEE - If this keyword is set, then the input is assumed to be in big endian format (e.g. an untranslated FITS array). This keyword only has an effect on little endian machines (e.g. a Linux box). OPTIONAL OUTPUT KEYWORD: ERRMSG - will contain a scalar string giving the error condition. If RESULT = 1 then ERRMSG will be an empty string. If this output keyword is not supplied, then the error message will be printed at the terminal. NOTES: The header and data must be *exactly* as originally written in the FITS file. By default, some FITS readers may alter keyword values (e.g. BSCALE) or append information (e.g. HISTORY or an inherited primary header) and this will alter the checksum value. PROCEDURES USED: CHECKSUM32, FITS_ASCII_ENCODE(), SXPAR() EXAMPLE: Verify the CHECKSUM keywords in the primary header/data unit of a FITS file 'test.fits' FITS_READ,'test.fits',data,hdr,/no_PDU,/NoSCALE print,FITS_TEST_CHECKSUM(hdr,data) Note the use of the /No_PDU and /NoSCALE keywords to avoid any alteration of the FITS header REVISION HISTORY: W. Landsman SSAI December 2002 Return quietly if CHECKSUM keywords not found W. Landsman May 2003 Add /NOSAVE to CHECKSUM32 calls when possible W. Landsman Sep 2004
(See $IDLUTILS_DIR/goddard/pro/fits/fits_test_checksum.pro)
FITS_WRITE
NAME: FITS_WRITE PURPOSE: To write a FITS primary data unit or extension. EXPLANATION: ***NOTE** This version of FITS_READ must be used with a post Sep 2006 version of FITS_OPEN. CALLING SEQUENCE: FITS_WRITE, filename_or_fcb, data, [header_in] INPUTS: FILENAME_OR_FCB: name of the output data file or the FITS control block returned by FITS_OPEN (called with the /WRITE or /APPEND) parameters. OPTIONAL INPUTS: DATA: data array to write. If not supplied or set to a scalar, a null image is written. HEADER_IN: FITS header keyword. If not supplied, a minimal basic header will be created. Required FITS keywords, SIMPLE, BITPIX, XTENSION, NAXIS, ... are added by FITS_WRITE and do not need to be supplied with the header. If supplied, their values will be updated as necessary to reflect DATA. INPUT KEYWORD PARAMETERS: XTENSION: type of extension to write (Default="IMAGE"). If not supplied, it will be taken from HEADER_IN. If not in either place, the default is "IMAGE". This parameter is ignored when writing the primary data unit. Note that binary and and ASCII table extensions already have a properly formatted header (e.g. with TTYPE* keywords) and byte array data. EXTNAME: EXTNAME for the extension. If not supplied, it will be taken from HEADER_IN. If not supplied and not in HEADER_IN, no EXTNAME will be written into the output extension. EXTVER: EXTVER for the extension. If not supplied, it will be taken from HEADER_IN. If not supplied and not in HEADER_IN, no EXTVER will be written into the output extension. EXTLEVEL: EXTLEVEL for the extension. If not supplied, it will be taken from HEADER_IN. If not supplied and not in HEADER_IN, no EXTLEVEL will be written into the output extension. /NO_ABORT: Set to return to calling program instead of a RETALL when an I/O error is encountered. If set, the routine will return a non-null string (containing the error message) in the keyword MESSAGE. If /NO_ABORT not set, then FITS_WRITE will print the message and issue a RETALL /NO_DATA: Set if you only want FITS_WRITE to write a header. The header supplied will be written without modification and the user is expected to write the data using WRITEU to unit FCB.UNIT. When FITS_WRITE is called with /NO_DATA, the user is responsible for the validity of the header, and must write the correct amount and format of the data. When FITS_WRITE is used in this fashion, it will pad the data from a previously written extension to 2880 blocks before writting the header. OUTPUT KEYWORD PARAMETERS: MESSAGE: value of the error message for use with /NO_ABORT HEADER: actual output header written to the FITS file. NOTES: If the first call to FITS_WRITE is an extension, FITS_WRITE will automatically write a null image as the primary data unit. Keywords and history in the input header will be properly separated into the primary data unit and extension portions when constructing the output header (See FITS_READ for information on the internal Header format which separates the extension and PDU header portions). EXAMPLES: Write an IDL variable to a FITS file with the minimal required header. FITS_WRITE,'newfile.fits',ARRAY Write the same array as an image extension, with a null Primary data unit. FITS_WRITE,'newfile.fits',ARRAY,xtension='IMAGE' Write 4 additional image extensions to the same file. FITS_OPEN,'newfile.fits',fcb FITS_WRITE,fcb,data1,extname='FLUX',extver=1 FITS_WRITE,fcb,err1,extname'ERR',extver=1 FITS_WRITE,fcb,data2,extname='FLUX',extver=2 FITS_WRITE,fcb,err2,extname='ERR',extver=2 FITS_CLOSE,FCB WARNING: FITS_WRITE currently does not completely update the file control block. When mixing FITS_READ and FITS_WRITE commands it is safer to use file names, rather than passing the file control block. PROCEDURES USED: FITS_OPEN, SXADDPAR, SXDELPAR, SXPAR() HISTORY: Written by: D. Lindler August, 1995 Work for variable length extensions W. Landsman August 1997 Converted to IDL V5.0 W. Landsman September 1997 PCOUNT and GCOUNT added for IMAGE extensions J. Graham October 1999 Write unsigned data types W. Landsman December 1999 Pad data area with zeros not blanks W. McCann/W. Landsman October 2000 Return Message='' to signal normal operation W. Landsman Nov. 2000 Ensure that required extension table keywords are in proper order W.V. Dixon/W. Landsman March 2001 Assume since V5.1, remove NaNValue keyword W. Landsman Nov. 2002 Removed obsolete !ERR system variable W. Landsman Feb 2004 Check that byte array supplied with table extension W. Landsman Mar 2004 Make number of bytes 64bit to avoid possible overflow W.L Apr 2006 Asuume FITS_OPEN has opened the file with /SWAP_IF_LITTLE_ENDIAN W. Landsman September 2006 Removes BZERO and BSCALE for floating point output, D. Lindler, Sep 2008
(See $IDLUTILS_DIR/goddard/pro/fits/fits_write.pro)
FIXPS
This program modifies an IDL-produced PostScript landscape mode file so that the output is right side up rather than upside down. In other words, it turns a so-called seascape file into an actual landscape file. Files that are not currently in landscape mode will be ignored. Tested with single and multiple page PostScript output from IDL 7.0.1 and 7.1. The program requires the `Coyote Library <http://www.idlcoyote.com/documents/programs.php>` to be installed on your machine. :Categories: Graphics, Utilities :Params: in_filename: in, required, type=string The name of an IDL-produced PostScript file in landscape mode. out_filename: in, optional, type=string The name of the fixed output PostScript file. If not provided, the input file is overwritten. Overwritting assumes proper read/write permission in TEMP directory and in the directory where the input file is located. :Keywords: a4: in, optional, type=boolean, default=0 Set this keyword if the PostScript file is using a A4 Europeran sized page. ledger: in, optional, type=boolean, default=0 Set this keyword if the PostScript file is using a US ledger size (11 x 17 inch) page. legal: in, optional, type=boolean, default=0 Set this keyword if the PostScript file is using a US legal size (8.5 x 14 inch) page. letter: in, optional, type=boolean, default=0 Set this keyword if the PostScript file is using a US letter size (8.5 x 11 inch) page. pagetype: in, optional, type=string, default="Letter" A generic way to set the page size. A string of "LETTER", "LEDGER", "LEGAL", or "A4". quiet: in, optional, type=boolean, default=0 Set this keyword to suppress error messages from the program. success: out, optional, type=boolean If this keyword is set to a named variable, then on output the variable will return a 1 if the operation was successful, and a 0 otherwise. Using this keyword also supresses the program's ability to "throw" an error. Informational messages are issued about program developments, but this program will allow the program caller to decide what to do with unsuccessful program completion. :Author: FANNING SOFTWARE CONSULTING:: David W. Fanning 1645 Sheely Drive Fort Collins, CO 80526 USA Phone: 970-221-0438 E-mail: david@idlcoyote.com Coyote's Guide to IDL Programming: http://www.idlcoyote.com :History: Change History:: Written by: David W. Fanning, 6 August 2009. Change to overwrite input file if output filename is not provided. 6 August 2009. DWF. Incorporated checks for non-landscape mode files and files that have already been fixed. 6 August 2009. DWF. Modified to fix multiple-page PostScript files and to work seamlessly with PS_START output. 8 August 2009. DWF. Ran into a problem in which the PostScript file is stored in the directory pointed to by the IDL_TMPDIR environment variable. Now check to see if the input filename is the same as the output filename and make a change, if necessary. 22 July 2010. DWF. Retreated to standard error handling with ERROR_MESSAGE as there are inevitable errors. 2 August 2010. DWF. Output file was created, even if not used. Now deleting file and issuing messages to explain why output file was not created. 1 November 2010. DWF. Added SUCCESS and QUIET keywords. 15 Novemember 2010. DWF. PostScript file structure changed in IDL 8. Made adjustment to find the PageBoundingBox line. 19 Dec 2010. DWF. :Copyright: Copyright (c) 2009-2012, Fanning Software Consulting, Inc.
(See $IDLUTILS_DIR/goddard/pro/coyote/fixps.pro)
FLEGENDRE
NAME: FLEGENDRE PURPOSE: Compute the first M terms in a Legendre polynomial expansion. EXPLANATION: Meant to be used as a supplied function to SVDFIT. This procedure became partially obsolete in IDL V5.0 with the introduction of the /LEGENDRE keyword to SVDFIT and the associated SVDLEG function. However, note that, unlike SVDLEG, FLEGENDRE works on vector values of X. CALLING SEQUENCE: result = FLEGENDRE( X, M) INPUTS: X - the value of the independent variable, scalar or vector M - number of term of the Legendre expansion to compute, integer scalar OUTPUTS: result - (N,M) array, where N is the number of elements in X and M is the order. Contains the value of each Legendre term for each value of X EXAMPLE: (1) If x = 2.88 and M = 3 then IDL> print, flegendre(x,3) ==> [1.00, 2.88, 11.9416] This result can be checked by explicitly computing the first 3 Legendre terms, 1.0, x, 0.5*( 3*x^2 -1) (2) Find the coefficients to an M term Legendre polynomial that gives the best least-squares fit to a dataset (x,y) IDL> coeff = SVDFIT( x,y,M,func='flegendre') The coefficients can then be supplied to the function POLYLEG to compute the best YFIT values for any X. METHOD: The recurrence relation for the Legendre polynomials is used to compute each term. Compare with the function FLEG in "Numerical Recipes" by Press et al. (1992), p. 674 REVISION HISTORY: Written Wayne Landsman Hughes STX April 1995 Converted to IDL V5.0 W. Landsman September 1997
(See $IDLUTILS_DIR/goddard/pro/math/flegendre.pro)
FLUX2MAG
NAME: FLUX2MAG PURPOSE: Convert from flux (ergs/s/cm^2/A) to magnitudes. EXPLANATION: Use MAG2FLUX() for the opposite direction. CALLING SEQUENCE: mag = flux2mag( flux, [ zero_pt, ABwave= ] ) INPUTS: flux - scalar or vector flux vector, in erg cm-2 s-1 A-1 OPTIONAL INPUT: zero_pt - scalar giving the zero point level of the magnitude. If not supplied then zero_pt = 21.1 (Code et al 1976) Ignored if the ABwave keyword is supplied OPTIONAL KEYWORD INPUT: ABwave - wavelength scalar or vector in Angstroms. If supplied, then FLUX2MAG() returns Oke AB magnitudes (Oke & Gunn 1983, ApJ, 266, 713). OUTPUT: mag - magnitude vector. If the ABwave keyword is set then mag is given by the expression ABMAG = -2.5*alog10(f) - 5*alog10(ABwave) - 2.406 Otherwise, mag is given by the expression mag = -2.5*alog10(flux) - zero_pt EXAMPLE: Suppose one is given wavelength and flux vectors, w (in Angstroms) and f (in erg cm-2 s-1 A-1). Plot the spectrum in AB magnitudes IDL> plot, w, flux2mag(f,ABwave = w), /nozero REVISION HISTORY: Written J. Hill STX Co. 1988 Converted to IDL V5.0 W. Landsman September 1997 Added ABwave keyword W. Landsman September 1998
(See $IDLUTILS_DIR/goddard/pro/astro/flux2mag.pro)
FM_UNRED
NAME: FM_UNRED PURPOSE: Deredden a flux vector using the Fitzpatrick (1999) parameterization EXPLANATION: The R-dependent Galactic extinction curve is that of Fitzpatrick & Massa (Fitzpatrick, 1999, PASP, 111, 63; astro-ph/9809387 ). Parameterization is valid from the IR to the far-UV (3.5 microns to 0.1 microns). UV extinction curve is extrapolated down to 912 Angstroms. CALLING SEQUENCE: FM_UNRED, wave, flux, ebv, [ funred, R_V = , /LMC2, /AVGLMC, ExtCurve= gamma =, x0=, c1=, c2=, c3=, c4= ] INPUT: WAVE - wavelength vector (Angstroms) FLUX - calibrated flux vector, same number of elements as WAVE If only 3 parameters are supplied, then this vector will updated on output to contain the dereddened flux. EBV - color excess E(B-V), scalar. If a negative EBV is supplied, then fluxes will be reddened rather than dereddened. OUTPUT: FUNRED - unreddened flux vector, same units and number of elements as FLUX OPTIONAL INPUT KEYWORDS R_V - scalar specifying the ratio of total to selective extinction R(V) = A(V) / E(B - V). If not specified, then R = 3.1 Extreme values of R(V) range from 2.3 to 5.3 /AVGLMC - if set, then the default fit parameters c1,c2,c3,c4,gamma,x0 are set to the average values determined for reddening in the general Large Magellanic Cloud (LMC) field by Misselt et al. (1999, ApJ, 515, 128) /LMC2 - if set, then the fit parameters are set to the values determined for the LMC2 field (including 30 Dor) by Misselt et al. Note that neither /AVGLMC or /LMC2 will alter the default value of R_V which is poorly known for the LMC. The following five input keyword parameters allow the user to customize the adopted extinction curve. For example, see Clayton et al. (2003, ApJ, 588, 871) for examples of these parameters in different interstellar environments. x0 - Centroid of 2200 A bump in microns (default = 4.596) gamma - Width of 2200 A bump in microns (default =0.99) c3 - Strength of the 2200 A bump (default = 3.23) c4 - FUV curvature (default = 0.41) c2 - Slope of the linear UV extinction component (default = -0.824 + 4.717/R) c1 - Intercept of the linear UV extinction component (default = 2.030 - 3.007*c2 OPTIONAL OUTPUT KEYWORD: ExtCurve - Returns the E(wave-V)/E(B-V) extinction curve, interpolated onto the input wavelength vector EXAMPLE: Determine how a flat spectrum (in wavelength) between 1200 A and 3200 A is altered by a reddening of E(B-V) = 0.1. Assume an "average" reddening for the diffuse interstellar medium (R(V) = 3.1) IDL> w = 1200 + findgen(40)*50 ;Create a wavelength vector IDL> f = w*0 + 1 ;Create a "flat" flux vector IDL> fm_unred, w, f, -0.1, fnew ;Redden (negative E(B-V)) flux vector IDL> plot,w,fnew NOTES: (1) The following comparisons between the FM curve and that of Cardelli, Clayton, & Mathis (1989), (see ccm_unred.pro): (a) - In the UV, the FM and CCM curves are similar for R < 4.0, but diverge for larger R (b) - In the optical region, the FM more closely matches the monochromatic extinction, especially near the R band. (2) Many sightlines with peculiar ultraviolet interstellar extinction can be represented with the FM curve, if the proper value of R(V) is supplied. (3) Use the 4 parameter calling sequence if you wish to save the original flux vector. PROCEDURE CALLS: CSPLINE(), POLY() REVISION HISTORY: Written W. Landsman Raytheon STX October, 1998 Based on FMRCurve by E. Fitzpatrick (Villanova) Added /LMC2 and /AVGLMC keywords, W. Landsman August 2000 Added ExtCurve keyword, J. Wm. Parker August 2000 Assume since V5.4 use COMPLEMENT to WHERE W. Landsman April 2006
(See $IDLUTILS_DIR/goddard/pro/astro/fm_unred.pro)
FORPRINT
NAME: FORPRINT PURPOSE: Print a set of vectors by looping over each index value. EXPLANATION: If W and F are equal length vectors, then the statement IDL> forprint, w, f is equivalent to IDL> for i = 0L, N_elements(w)-1 do print,w[i],f[i] CALLING SEQUENCE: forprint, v1,[ v2, v3, v4,....v18, FORMAT = , TEXTOUT = ,STARTLINE =, SUBSET=, NUMLINE =, /SILENT, COMMENT= ] INPUTS: V1,V2,...V18 - Arbitary IDL vectors. If the vectors are not of equal length then the number of rows printed will be equal to the length of the smallest vector. Up to 18 vectors can be supplied. OPTIONAL KEYWORD INPUTS: TEXTOUT - Controls print output device, defaults to !TEXTOUT textout=1 TERMINAL using /more option if available textout=2 TERMINAL without /more option textout=3 file 'forprint.prt' textout=4 file 'laser.tmp' textout=5 user must open file textout = filename (default extension of .prt) textout=7 Append to <program>.prt file if it exists COMMENT - String scalar or vector to write to the first line of output file if TEXTOUT > 2. By default, FORPRINT will write a time stamp on the first line. Use /NOCOMMENT if you don't want FORPRINT to write anything in the output file. If COMMENT is a vector then one line will be written for each element. FORMAT - Scalar format string as in the PRINT procedure. The use of outer parenthesis is optional. Ex. - format="(F10.3,I7)" This program will automatically remove a leading "$" from incoming format statements. Ex. - "$(I4)" would become "(I4)". If omitted, then IDL default formats are used. /NOCOMMENT - Set this keyword if you don't want any comment line line written as the first line in a harcopy output file. /SILENT - Normally, with a hardcopy output (TEXTOUT > 2), FORPRINT will print an informational message. If the SILENT keyword is set and non-zero, then this message is suppressed. SUBSET - Index vector specifying elements to print. No error checking is done to make sure the indicies are valid. The statement IDL> forprint,x,y,z,subset=s is equivalent to IDL> for i=0,n-1 do print, x[s[i]], y[s[i]], z[s[i]] STARTLINE - Integer scalar specifying the first line in the arrays to print. Default is STARTLINE = 1, i.e. start at the beginning of the arrays. (If a SUBSET keyword is supplied then STARTLINE refers to first element in the subscript vector.) /STDOUT - If set, the force standard output unit (=-1) if not writing to a file. This allows the FORPINT output to be captured in a journal file. Only needed for non-GUI terminals WIDTH - Line width for wrapping, passed onto OPENW when using hardcopy. OUTPUTS: None SYSTEM VARIABLES: If keyword TEXTOUT is not used, the default is the nonstandard keyword !TEXTOUT. If you want to use FORPRINT to write more than once to the same file, or use a different file name then set TEXTOUT=5, and open and close then file yourself (see documentation of TEXTOPEN for more info). One way to add the non-standard system variables !TEXTOUT and !TEXTUNIT is to use the procedure ASTROLIB EXAMPLE: Suppose W,F, and E are the wavelength, flux, and epsilon vectors for a spectrum. Print these values to a file 'output.dat' in a nice format. IDL> fmt = '(F10.3,1PE12.2,I7)' IDL> forprint, F = fmt, w, f, e, TEXT = 'output.dat' PROCEDURES CALLED: TEXTOPEN, TEXTCLOSE REVISION HISTORY: Written W. Landsman April, 1989 Keywords textout and format added, J. Isensee, July, 1990 Made use of parenthesis in FORMAT optional W. Landsman May 1992 Added STARTLINE keyword W. Landsman November 1992 Set up so can handle 18 input vectors. J. Isensee, HSTX Corp. July 1993 Handle string value of TEXTOUT W. Landsman, HSTX September 1993 Added NUMLINE keyword W. Landsman, HSTX February 1996 Added SILENT keyword W. Landsman, RSTX, April 1998 Much faster printing to a file W. Landsman, RITSS, August, 2001 Use SIZE(/TNAME) instead of DATATYPE() W. Landsman SSAI October 2001 Fix skipping of first line bug introduced Aug 2001 W. Landsman Nov2001 Added /NOCOMMENT keyword, the SILENT keyword now controls only the display of informational messages. W. Landsman June 2002 Skip PRINTF if IDL in demo mode W. Landsman October 2004 Assume since V5.4 use BREAK instead of GOTO W. Landsman April 2006 Add SUBSET keyword, warning if different size vectors passed. P.Broos,W.Landsman. Aug 2006 Change keyword_set() to N_elements W. Landsman Oct 2006 Added /STDOUT keyword W. Landsman Oct 2006 Fix error message for undefined variable W. Landsman April 2007 Added WIDTH keyword J. Bailin Nov 2010 Allow multiple (vector) comment lines W. Landsman April 2011
(See $IDLUTILS_DIR/goddard/pro/misc/forprint.pro)
FPUFIX
NAME: FPUFIX PURPOSE: This is a utility routine to examine a variable and fix problems that will create floating point underflow errors. AUTHOR: FANNING SOFTWARE CONSULTING David Fanning, Ph.D. 1645 Sheely Drive Fort Collins, CO 80526 USA Phone: 970-221-0438 E-mail: david@idlcoyote.com Coyote's Guide to IDL Programming: http://www.idlcoyote.com CATEGORY: Utilities CALLING SEQUENCE: fixedData = FPUFIX(data) ARGUMENTS: data : A numerical variable to be checked for values that will cause floating point underflow errors. Suspect values are set to 0. KEYWORDS: None. RETURN VALUE: fixedData: The output is the same as the input, except that any values that will cause subsequent floating point underflow errors are set to 0. COMMON BLOCKS: None. EXAMPLES: data = FPTFIX(data) RESTRICTIONS: None. MODIFICATION HISTORY: Written by David W. Fanning, from Mati Meron's example FPU_FIX. Mati's program is more robust that this (ftp://cars3.uchicago.edu/midl/), but this serves my needs and doesn't require other programs from Mati's library. 24 February 2006.
(See $IDLUTILS_DIR/goddard/pro/coyote/fpufix.pro)
FREBIN
NAME: FREBIN PURPOSE: Shrink or expand the size of an array an arbitary amount using interpolation EXPLANATION: FREBIN is an alternative to CONGRID or REBIN. Like CONGRID it allows expansion or contraction by an arbitary amount. ( REBIN requires integral factors of the original image size.) Like REBIN it conserves flux by ensuring that each input pixel is equally represented in the output array. CALLING SEQUENCE: result = FREBIN( image, nsout, nlout, [ /TOTAL] ) INPUTS: image - input image, 1-d or 2-d numeric array nsout - number of samples in the output image, numeric scalar OPTIONAL INPUT: nlout - number of lines in the output image, numeric scalar If not supplied, then set equal to 1 OPTIONAL KEYWORD INPUTS: /total - if set, the output pixels will be the sum of pixels within the appropriate box of the input image. Otherwise they will be the average. Use of the /TOTAL keyword conserves surface flux. OUTPUTS: The resized image is returned as the function result. If the input image is of type DOUBLE or FLOAT then the resized image is of the same type. If the input image is BYTE, INTEGER or LONG then the output image is usually of type FLOAT. The one exception is expansion by integral amount (pixel duplication), when the output image is the same type as the input image. EXAMPLE: Suppose one has an 800 x 800 image array, im, that must be expanded to a size 850 x 900 while conserving surface flux: IDL> im1 = frebin(im,850,900,/total) im1 will be a 850 x 900 array, and total(im1) = total(im) NOTES: If the input image sizes are a multiple of the output image sizes then FREBIN is equivalent to the IDL REBIN function for compression, and simple pixel duplication on expansion. If the number of output pixels are not integers, the output image size will be truncated to an integer. The platescale, however, will reflect the non-integer number of pixels. For example, if you want to bin a 100 x 100 integer image such that each output pixel is 3.1 input pixels in each direction use: n = 100/3.1 ; 32.2581 image_out = frebin(image,n,n) The output image will be 32 x 32 and a small portion at the trailing edges of the input image will be ignored. PROCEDURE CALLS: None. HISTORY: Adapted from May 1998 STIS version, written D. Lindler, ACC Added /NOZERO, use INTERPOLATE instead of CONGRID, June 98 W. Landsman Fixed for nsout non-integral but a multiple of image size Aug 98 D.Lindler DJL, Oct 20, 1998, Modified to work for floating point image sizes when expanding the image. Improve speed by addressing arrays in memory order W.Landsman Dec/Jan 2001
(See $IDLUTILS_DIR/goddard/pro/image/frebin.pro)
FSC_BASE_FILENAME
NAME: FSC_BASE_FILENAME PURPOSE: The purpose of this is to extract from a long file path, the base file name. That is, the name of the actual file without the preceeding directory information or the final file extension. The directory information and file extension can be obtained via keywords. The file is named so as not to interfere with FILE_BASENAME, which was introduced in IDL 6.0 and performs a similar function. AUTHOR: FANNING SOFTWARE CONSULTING David Fanning, Ph.D. 1645 Sheely Drive Fort Collins, CO 80526 USA Phone: 970-221-0438 E-mail: david@idlcoyote.com Coyote's Guide to IDL Programming: http://www.idlcoyote.com/ CATEGORY: Utility. CALLING SEQUENCE: baseFilename = FSC_Base_Filename(thePath) INPUTS: thePath: This is the file path you wish to extract a base file name from. It is a string variable of the sort returned from Dialog_Pickfile. KEYWORDS: DIRECTORY: The directory information obtained from the input file path. The directory always ends in a directory separator character. EXTENSION: The file extension associated with the input file path. PATH_SEPARATOR: The string to use as a path separator. If undefined, the output of PATH_SEP() will be used. RETURN_VALUE: baseFilename: The base filename, stripped of directory and file extension information. RESTRICTIONS: This is a quick and dirty program. It has been tested on Windows machines and *lightly* tested on UNIX machines. Please contact me at the e-mail address above if you discover problems. EXAMPLE: IDL> thePath = "C:\rsi\idl7.8\lib\jester.pro" IDL> Print, FSC_Base_Filename(thePath, Directory=theDirectory, Extension=theExtension) jester IDL> Print, theDirectory C:\rsi\idl7.8\lib\ IDL> Print, theExtension pro MODIFICATION HISTORY: Written by: David W. Fanning, 31 July 2003. Modified by KaRo, 13 Feb. 2005 to allow dots in the filename. Added PATH_SEPARATOR keyword. 25 July 2005. DWF. Added ability to recongnize directory by path separator in last character. 19 Sept 2005. DWF. If directory is blank (because a relative filename was passed), set to current directory. 6 Aug 2009. DWF. There were a couple of instances where the directory did NOT end in a path separator. Fixed. 24 Feb 2012. DWF.
(See $IDLUTILS_DIR/goddard/pro/coyote/fsc_base_filename.pro)
FSC_DROPLIST
NAME: FSC_DROPLIST PURPOSE: The purpose of this compound widget is to provide an alternative to the DROPLIST widget offered in the IDL distribution. What has always annoyed me about a droplist is that you can't get the current "value" of a droplist easily. This compound widget makes this and other tasks much easier. AUTHOR: FANNING SOFTWARE CONSULTING David Fanning, Ph.D. 1645 Sheely Drive Fort Collins, CO 80526 USA Phone: 970-221-0438 E-mail: david@idlcoyote.com Coyote's Guide to IDL Programming: http://www.idlcoyote.com/ CATEGORY: General programming. CALLING SEQUENCE: droplistObj = FSC_Droplist(parent, Title='Animals: ", Value=['Dog'. 'Cat', 'Coyote'], Index=2) The return value of the FSC_Droplist (droplistObj in this example) is an object reference. Interaction with the droplist will occur through object methods. INPUT PARAMETERS: parent -- The parent widget ID of the compound widget. Required. INPUT KEYWORDS: Any keyword that is appropriate for the Widget_Droplist function can be used. In addition, these keywords are explicitly defined. EVENT_FUNC -- Set this keyword to the name of an Event Handler Function. EVENT_PRO -- Set this keyword to the name of an Event Handler Procedure. FORMAT -- A format specifier for the "format" of the values in the droplist. INDEX -- The index number of the current selection. SPACES -- A two-element array that indicates the number of blank spaces to be added to the the beginning and end of the formatted values. If a single number is provided, this number of blank spaces is added to both the beginning and the end of the value. TITLE -- The title of the droplist widget. UNAME -- The user name of the droplist widget. (Only available in IDL 5.2 and higher.) UVALUE -- The normal "user value" of the droplist. VALUE -- An array of the droplist "selections". May be any data type. COMMON BLOCKS: None. DEPENDENCIES: Requires ERROR_MESSAGE from the Coyote Library.. EVENT STRUCTURE: An event is returned each time the droplist value is changed. The event structure is defined like this: event = { FSC_DROPLIST_EVENT, $ ; The name of the event structure. ID: 0L, $ ; The ID of the compound widget's top-level base. TOP: 0L, $ ; The widget ID of the top-level base of the hierarchy. HANDLER: 0L, $ ; The event handler ID. Filled out by IDL. INDEX: 0L, $ ; The index number of the current selection. SELECTION:Ptr_New() $ ; A pointer to the current selection "value". SELF:Obj_New() } ; The object reference of the compound widget. PUBLIC OBJECT METHODS: GetID -- A function with no arguments that returns the widget identifier of the droplist widget. droplistID = droplistObj->GetID() GetIndex -- A function with no arguments that returns the index number of the current droplist selection. currentIndex = droplistObj->GetIndex() GetSelection -- A function with no arguments that returns the current droplist selection. currentSelection = droplistObj->GetSelection() GetUValue -- A function with no arguments that returns the "user value" of the compound widget i.e., the value set with the UVALUE keyword). myUValue = droplistObj->GetUValue() GetValues -- A function with no arguments that returns the "values" or "selections" for the droplist. possibleSelections = droplistObj->GetValues() Resize -- A procedure that sets the X screen size of the droplist. It is defined like this: PRO Resize, newSize, ParentSize=parentSize The "newSize" keyword is the new X screen size. If this argument is missing, the screen X size of the compound widget's parent is used. The parentSize keyword is an output keyword that returns the X screen size of the compound widget's parent. droplistObj->Resize, 400 Note that not all devices (e.g., X Windows devices) support droplist resizing. SetIndex -- A procedure that sets the current droplist selection based on the given index. This is equivalent to Widget_Control, droplistID, Set_Droplist_Select=newIndex droplistObj->SetIndex, newIndex SetSelection -- Whereas a regular droplist widget can only be set by index number, this compound widget can also be set by a "selection". The new selection can be any data type and corresponds to one of the "values" of the droplist. droplistObj->SetSelection, newSelection SetValues -- Sets the possible selections of the droplist widget. The CurrentIndex keyword will allow the current index of the selection to be changed to: newChoices = ['dog', 'cat', 'coyote'] droplistObj->SetValues, newChoices, CurrentIndex=2 EXAMPLE: An example program is provided at the end of the FSC_DROPLIST code. To run it, type these commands: IDL> .Compile FSC_DROPLIST IDL> Example MODIFICATION HISTORY: Written by: David W Fanning, 17 Jan 2000. DWF. Added FORMAT and SPACES keywords 28 April 2000. DWF. Fixed a small problem with event processing when the EVENT_FUNC keyword was used. 29 Dec 2000. DWF. Attached the UNAME value to the TLB of the compound widget instead of to the droplist widget itself. 11 Jan 2001. DWF. Fixed a problem when the droplist was part of a modal widget and used the EVENT_PRO keyword. 27 Oct 2003. DWF. Added a SetValue method for setting all the values in the droplist at once. 12 Nov 2004. DWF. Fixed type on line 346/ 6 Feb 2008. DWF.
(See $IDLUTILS_DIR/goddard/pro/coyote/fsc_droplist.pro)
FSC_FIELD
NAME: FSC_FIELD PURPOSE: The purpose of this compound widget is to provide an alternative to the CW_FIELD widget offered in the IDL distribution. One weakness of the CW_FIELD compound widget is that the text widgets do not look editable to the users on Windows platforms. This program corrects that deficiency and adds some features that I think will be helpful. For example, you can now assign an event handler to the compound widget, ask for positive numbers only, and limit the number of digits in a number, or the number of digits to the right of a decimal point. The program is written as a widget object, which allows the user to call object methods directly, affording even more flexibility in use. This program replaces the earlier programs FSC_INPUTFIELD and COYOTE_FIELD. The program consists of a label widget next to a one-line text widget. The "value" of the compound widget is shown in the text widget. If the value is a number, it will not be possible (generally) to type alphanumeric values in the text widget. String values behave like strings in any one-line text widget. AUTHOR: FANNING SOFTWARE CONSULTING David Fanning, Ph.D. 1645 Sheely Drive Fort Collins, CO 80526 USA Phone: 970-221-0438 E-mail: david@idlcoyote.com Coyote's Guide to IDL Programming: http://www.idlcoyote.com/ CATEGORY: General programming. TYPICAL CALLING SEQUENCE: fieldID = FSC_FIELD(parent, Title="X Size:", Value=256, Object=fieldObject, Digits=3) INPUT PARAMETERS: parent -- The parent widget ID of the compound widget. Required. INPUT KEYWORDS: COLUMN Set this keyword to have the Label widget above the Text widget. The default is to have the Label widget in a row with the Text widget. CR_ONLY Set this keyword if you only want Carriage Return events returned to your event handler. If this keyword is not set, all events are returned. Setting this keyword has no effect unless either the EVENT_PRO or EVENT_FUNC keyword is used. DECIMAL Set this keyword to the number of digits to the right of the decimal point in floating point or double precision numbers. Ignored for STRING values. DIGITS Set this keyword to the number of digits permitted in integer numbers. EVENT_FUNC Set this keyword to the name of an event handler function. If this keyword is undefined and the Event_Pro keyword is undefined, all compound widget events are handled internally and not passed on to the parent widget. EVENT_PRO Set this keyword to the name of an event handler procedure. If this keyword is undefined and the Event_Func keyword is undefined, all compound widget events are handled internally and not passed on to the parent widget. FIELDFONT The font name for the text in the text widget. FRAME Set this keyword to put a frame around the compound widget. FOCUS_EVENTS Set this keyword to enable event generation for keyboard focus events. Ignored unless EVENT_FUNC or EVENT_PRO keywords are specified. HIGHLIGHT Set this keyword to highlight the existing text if the widget gain the keyboard focus. This keyword MUST be set for tabbing to work naturally in IDL 6.2 and higher. LABEL_LEFT Set this keyword to align the text on the label to the left. LABEL_RIGHT Set this keyword to align the text on the label to the right. LABELFONT The font name for the text in the label widget. LABELSIZE The X screen size of the label widget. NAME A string containing the name of the object. The default is ''. NOEDIT Set this keyword to allow no user editing of the input text widget. NONSENSITIVE Set this keyword to make the input text widget non-sensitive. POSITIVE Set this keyword if you want only positive numbers allowed. SCR_XSIZE The X screen size of the compound widget. SCR_YSIZE The Y screen size of the compound widget. TITLE The string text placed on the label widget. UNDEFINED Set this keyword to the value to use for "undefined" values. If not set, then !Value.F_NAN is used for numerical fields and a NULL string is used for string fields. This applies to values obtained with the GET_VALUE method or the GET_VALUE function. UVALUE A user value for any purpose. VALUE The "value" of the compound widget. Any type of integer, floating, or string variable is allowed. The data "type" is determined automatically from the value supplied with this keyword. Be sure you set the type appropriately for your intended use of the value. XSIZE The X size of the text widget in the usual character units. OUTPUT KEYWORDS: OBJECT Set this keyword to a named variable to receive the compound widget's object reference. This is required if you wish to call methods on the object. Note that the object reference is also available in the event structure generated by the widget object. Note that the object reference will be necessary if you want to get or set values in the compound widget. COMMON BLOCKS: None. RESTRICTIONS: Requires DBLTOSTR from the Coyote Library: http://www.idlcoyote.com/programs/dbltostr.pro EVENT STRUCTURE: All events are handled internally unless either the Event_Pro or Event_Func keywords are used to assign an event handler to the compound widget. By default all events generated by the text widget are passed to the assigned event handler. If you wish to receive only Carriage Return events, set the CR_Only keyword. event = { FSC_FIELD_EVENT, $ ; The name of the event structure. ID: 0L, $ ; The ID of the compound widget's top-level base. TOP: 0L, $ ; The widget ID of the top-level base of the hierarchy. HANDLER: 0L, $ ; The event handler ID. Filled out by IDL. OBJECT: Obj_New(), $ ; The "self" object reference. Provided so you can call methods. VALUE: Ptr_New(), $ ; A pointer to the widget value. TYPE:"" ; A string indicating the type of data in the VALUE field. } Note that if the field is "empty", the VALUE will be a pointer to an undefined variable. You should check this value before you use it. You code will look something like this: IF N_Elements(*event.value) EQ 0 THEN $ Print, 'Current Value UNDEFINED.' ELSE $ Print, 'Current Value: ', *event.value GETTING and SETTING VALUES: Almost all the properties of the widget can be obtained or set via the object's GetProperty and SetProperty methods (described below). Traditional compound widgets have the ability to get and set the "value" of the compound widget identifier (e.g., fieldID in the calling sequence above). Unfortunately, it is impossible to retreive a variable in this way when the variable is undefined. In practical terms, this means that the undefined variable must be set to *something*. You can determine what that something is with the UNDEFINED keyword, or I will set it to !VALUES.F_NAN for numerical fields and to the null string for string fields. In any case, you will have to check for undefined variables before you try to do something with the value. For a numerical field, the code might look something like this: fieldID = FSC_FIELD(parent, Title="X Size:", Value=256, Object=fieldObject, Digits=3) currentValue = fieldObject->Get_Value() IF Finite(currentValue) EQ 0 THEN Print, 'Value is Undefined' ELSE Print, currentValue Additional examples are provided in the numerical example fields in Example Program below. Setting the value of the compound widget is the same as calling the Set_Value method on the object reference. In other words, these two statements are equivalent. fieldObject->Set_Value, 45.4 Widget_Control, fieldID, Set_Value=45.4 The data type of the value is determined from the value itself. Be sure you set it appropriately. OBJECT PROCEDURE METHODS: GetProperty -- This method allows various properties of the widget to be returned via output keywords. The keywords that are available are: CR_Only -- A flag, if set, means only report carriage return events. DataType -- The data type of the field variable. Decimal -- Set this keyword to the number of digits to the right of the decimal point in FLOATVALUE and DOUBLEVALUE numbers. Digits -- Set this keyword to the number of digits permitted in INTERGERVALUE and LONGVALUE numbers. Event_Func -- The name of the event handler function. Event_Pro -- The name of the event handler function. Has_Focus -- Set to 1 if the text widget currently has the keyboard focus. Highlight -- The highlight flag. NoEdit -- The NoEdit flag. NonSensitive -- The NonSensitive flag. Undefined -- The "value" of any undefined value. UValue -- The user value assigned to the compound widget. Value -- The "value" of the compound widget. Name -- A scalar string name of the object. Resize -- This method allows you to resize the compound widget's text field. The value parameter is an X screen size for the entire widget. The text widget is sized by using the value obtained from this value minus the X screen size of the label widget. objectRef->Resize, screen_xsize_value Set_Value -- This method allows you to set the "value" of the field. It takes one positional parameter, which is the value. objectRef->Set_Value, 5 SetProperty -- This method allows various properties of the widget to be set via input keywords. The keywords that are available are: CR_Only -- Set this keyword if you only want Carriage Return events. Decimal -- Set this keyword to the number of digits to the right of the decimal point in FLOAT and DOUBLE numbers. Digits -- Set this keyword to the number of digits permitted in INTERGER and LONG numbers. Event_Func -- Set this keyword to the name of an Event Function. Event_Pro -- Set this keyword to the name of an Event Procedure. Highlight -- Set this keyword to highlight the existing text when the widget gets the keyboard focus LabelSize -- The X screen size of the Label Widget. Name -- A scalar string name of the object. (default = '') NoEdit -- Set this keyword to make the text widget uneditable NonSensitive -- Set this keyword to make the widget nonsensitive Scr_XSize -- The X screen size of the text widget. Scr_YSize -- The Y screen size of the text widget. Title -- The text to go on the Label Widget. UValue -- A user value for any purpose. Value -- The "value" of the compound widget. XSize -- The X size of the Text Widget. SetTabNext -- This method allows you to specify which field to go to when a TAB character is typed in the text widget. See the Example program below for an example of how to use this method. OBJECT FUNCTIONS METHODS: Get_Value -- Returns the "value" of the field. No parameters. Will be undefined if a "number" field is blank. Should be checked before using: IF N_Elements(objectRef->Get_Value()) NE 0 THEN Print, Value is: ', objectRef->Get_Value() GetID -- Returns the widget identifier of the compound widget's top-level base. (The first child of the parent widget.) No parameters. GetLabelSize -- Returns the X screen size of the label widget. No parameters. GetTextID -- Returns the widget identifier of the compound widget's text widget. No parameters. GetTextSize -- Returns the X screen size of the text widget. No parameters. PRIVATE OBJECT METHODS: Although there is really no such thing as a "private" method in IDL's object implementation, some methods are used internally and not meant to be acessed publicly. Here are a few of those methods. I list them because it may be these private methods are ones you wish to override in subclassed objects. MoveTab -- This method moves the focus to the widget identified in the "next" field, which must be set with the SetTabNext method. No parameters. Called automatically when a TAB character is typed in the text widget. Text_Events -- The main event handler method for the compound widget. All text widget events are processed here. ReturnValue -- This function method accepts a string input value and converts it to the type of data requested by the user. Validate -- This function method examines all text input and removes unwanted characters, depending upon the requested data type for the field. It makes it impossible, for example, to type alphanumeric characters in an INTEGER field. EXAMPLE: An example program is provided at the end of the FSC_FIELD code. To run it, type these commands: IDL> .Compile FSC_Field IDL> Example MODIFICATION HISTORY: Written by: David W. Fanning, 18 October 2000. Based heavily on an earlier FSC_INPUTFIELD program and new ideas about the best way to write widget objects. Added LABEL_LEFT, LABEL_RIGHT, and UNDEFINED keywords. 29 Dec 2000. DWF. Modified the way the value is returned in the GET_VALUE method and the GET_VALUE function. Modified Example program to demonstrate. 30 Dec 2000. DWF. Added NOEDIT and NONSENSITIVE keywords, with corresponding SETEDIT and SETSENNSITIVE methods. 19 Jan 2001. DWF. Actually followed through with the changes I _said_" I made 29 Dec 2000. (Don't ask....) 13 June 2001. DWF. Added GetTextSize and GetLabelSize methods for obtaining the X screen size of the text and label widgets, respectively. 21 July 2001. DWF. Fixed a problem in SetProperty method where I was setting self.xsize, which doesn't exist. 24 April 2002. DWF. Small modification to the SetEdit method. 6 August 2003. DWF. Added Highlight keyword. Ported Focus_Events keyword from fsc_inputfield.pro. Updated documentation. 17 November 2004. DWF and Benjamin Hornberger Added Has_Focus keyword to the GetProperty method. 18 November 2004. Benjamin Hornberger Fixed bug in GetProperty method (set value to *self.undefined if *self.value is undefined. 24 Feb 2004. Benjamin Hornberger Modified FOCUS_EVENTS keyword handling so that *all* focus events are now passed to specified event handlers. Check event.select to see if the widget is gaining or losing focus. 10 August 2005. DWF. Added new tabbing functionality, introduced in IDL 6.2. To use tabbing functionality natually, the HIGHTLIGHT keywords must be set. See included EXAMPLE program for details. 10 August 2005. DWF. Added functionality to covert double precision values to strings properly. 30 Nov 2005. DWF. Set the default fonts to be the current widget font, rather than the default widget font. 4 Oct 2008. DWF. Fixed a problem with validating a float or double value when it was written with exponential notation. 2 April 2010. DWF.
(See $IDLUTILS_DIR/goddard/pro/coyote/fsc_field.pro)
FSC_FILESELECT
NAME: FSC_FILESELECT PURPOSE: The purpose of this compound widget is to provide a means by which the user can type or select a file name. The program is written as an "object widget", meaning that the guts of the program is an object of class FSC_FILESELECT. This is meant to be an example of the obvious advantages of writing compound widget programs as objects. AUTHOR: FANNING SOFTWARE CONSULTING David Fanning, Ph.D. 1645 Sheely Drive Fort Collins, CO 80526 USA Phone: 970-221-0438 E-mail: david@idlcoyote.com Coyote's Guide to IDL Programming: http://www.idlcoyote.com/ CATEGORY: General programming. CALLING SEQUENCE: filenameID = FSC_FileSelect(parent) INPUT PARAMETERS: parent -- The parent widget ID of the compound widget. Required. INPUT KEYWORDS: Event_Pro -- The event handler procedure for this compound widget.By default: "". Event_Func -- The event handler function for this compound widget. By default: "". If neither EVENT_PRO or EVENT_FUNC is defined, program events are handled internally by the compound widget. DirectoryName -- The initial name of the directory. By defaut: current directory. Filename -- The initial file name in the filename text widget. Filter -- The file filter. By default: "*". Frame -- Set this keyword for a frame around the compound widget. LabelFont -- The font for the label widget. By default: "". LabelName -- The text on the label widgt. By default: "Filename: ". LabelSize -- The X screen size of the label widget. By default: 0. MustExist -- A flag that indicates selected files must exist. By default: 0. NoMaxSize -- A flag to prohibit automatic text widget sizing. By default: 0. If this keyword is not set, the compound widget will automatically resize itself to the largest widget in its parent base widget. It will do this by changing the size of the text widgets holding the file and directory names. Read -- Set this keyword to have file selection for reading a file. By default: 1. SelectDirectory -- The default directory for file selection. In other words, this is the default directory for DIALOG_PICKFILE, which is accessed via the BROWSE buttons. SelectFont -- The font for the "Browse" button. By default: "". SelectTitle -- The title bar text on the file selection dialog. By default: "Select a File...". TextFont -- The font for the filename text widget. By default: "". UValue -- User value for any purpose. Write -- Set this keyword to open a file for writing. By default: 0. XSize -- The X size of the text widget holding the filename. By default: StrLen(filename) * 1.5 > 40. OUTPUT KEYWORDS: ObjectRef -- Assign this keyword to an output variable that will hold the internal object reference. With the object reference you can call object methods to easily change many properties of the compound widget. COMMON BLOCKS: None. RESTRICTIONS: Requires the folling files from the Coyote Library: http://www.idlcoyote.com/programs/error_message.pro EVENT STRUCTURE: All events are handled internally unless either the Event_Pro or Event_Func keywords are used to assign an event handler to the compound widget. All events generated by the text widgets are passed to the assigned event handler. event = { CW_FILESELECT, $ ; The name of the event structure. ID: 0L, $ ; The ID of the compound widget's top-level base. TOP: 0L, $ ; The widget ID of the top-level base of the hierarchy. HANDLER: 0L, $ ; The event handler ID. Filled out by IDL. Basename: "", $ ; The base filename without directory specifiers. Filename: "", $ ; The fully qualified filename. Directory: "", $ ; The name of the current file directory. } EXAMPLE: An example program is provided at the end of the FSC_FILESELECT code. To run it, type these commands: IDL> .Compile fsc_fileselect IDL> Example Or, if you want to obtain the object reference, type this: IDL> Example, theObject Now you can call the object's methods. For example: IDL theObject->SetProperty, XSize=150 GETTING and SETTING VALUES: So as not to disrupt the accepted paradigm in using compound widgets, you can use the return value of the FSC_FILESELECT function with WIDGET_CONTROL to get and set the "value" of the widget. Widget_Control, filenameID, Set_Value='C:\RSI\IDL52\DATA\cyclone.dat' The program will automatically separate the file name portion of the value from the directory portion and put things in the correct text widgets. Similarly, you can get the "value" of the widget: Widget_Control, filenameID, Get_Value=theValue Print, theValue C:\RSI\IDL52\DATA\cyclone.dat The return value is the fully qualified file path to the file. USING OBJECT METHODS to CHANGE PROGRAM PROPERTIES: If you obtain the object reference, you have a great deal more control over the properties of the compound widget. You obtain the object reference by calling the function like this: filenameID = FSC_FILESELECT(parent, ObjectRef=theObject) OBJECT PROCEDURE METHODS: GetProperty -- This method allows various properties of the widget to be returned via output keywords. The keywords that are available are: DirectoryName -- The current directory. Event_Func -- The name of the event handler function for this compound widget. Event_Pro -- The name of the event handler procedure for this compound widget. Filename -- The current base filename. Filter -- The current file filter. LabelName -- The text on the label widget. LabelSize -- The X screen size of the label widget. MustExist -- A flag that indicates selected files must exist to be selected. Parent -- The parent widget of the compound widget. Read=read -- The file selection for reading flag. SelectTitle -- The title bar text on the file selection dialog. TLB -- The top-level base of the compound widget. UValue -- The user value of the compound widget. Write -- The file selection for writing flag. XSize -- The X size of the text widget holding the filename. LabelSize -- This method makes sure that the directory name and file name labels are the same size. Normally, this procedure is called internally. No parameters. MatchSize -- This method resizes the compound widget so that it is as long as the the longest widget in the parent base widget. This is done automatically upon realization unless the NOMAXSIZE keyword is set. The method aids in writing resizeable widget programs. SetProperty -- This method allows various properties of the widget to be set via input keywords. The keywords that are available are: DirectoryName -- The current directory. Event_Func -- The name of the event handler function for this compound widget. Event_Pro -- The name of the event handler procedure for this compound widget. Filename -- The current base filename. Filter -- The current file filter. LabelName -- The text on the label widget. LabelSize -- The X screen size of the label widget. MustExist -- A flag that indicates selected files must exist to be selected. Read -- The file selection for reading flag. SelectTitle -- The title bar text on the file selection dialog. UValue -- The user value of the compound widget. Write -- The file selection for writing flag. XSize -- The X size of the text widget holding the filename. TextSelect - Allows you to create a selection in filename text widget. See the documentation for the SET_TEXT_SELECT keyword to Widget_Control. selection -- A two-element array containing the starting position and selection length. OBJECT FUNCTION METHODS: GetFileName -- Returns the fully qualified filename. No parameters. GetTLB -- Returns the top-level base ID of the compound widget. No Parameters. Inspect_DirectoryName -- Inspects the directory name for correctness. Requires one positional parameter. directoryName -- The name of the directory from the directory text widget. textSelection -- The current text selection position. At the moment all this does is remove any blank characters from either end of the directory name and makes sure the last character of the directory name does not end in a subdirectory specifier (except for VMS). Inspect_Filename -- Inspects the file name for correctness. Requires one positional parameter. filename -- The name of the file from the filename text widget. textSelection -- The current text selection position. At the moment all this does is remove any blank characters from either end of the file name MODIFICATION HISTORY: Written by: David W. Fanning, 21 NOV 1999. Fixed bug in File Name selection button. 18 MAR 2000. DWF. Fixed an error in which directory the Browse buttons should start searching. 29 SEP 2000. DWF. Previously returned events only for typing in text widgets. Now Browse button events are also returned. 29 SEP 2000. DWF. Fixed a bug in setting the file filter. 29 SEP 2000. DWF. Removed the Directory Browse button 10 AUG 2002. DWF. Added ERROR_MESSAGE to error handling. 10 AUG 2002. DWF. Changed the ability to specify a file filter as a string array, instead of just as a scalar string. This required the use of a pointer, which meant that I had to remove the FILTER field from the CW_FILESELECT event structure to avoid likely memory leakage. This is a dangerous change because it means programs that relied on this (I expect there are very, very few) will break and it goes against my philosopy of keeping my programs backward compatible. Let me know if you have problems. In testing, I discoved no problems in my own code. 31 OCT 2002. DWF. Fixed a problem with DIALOG_PICKFILE that sometimes allowed users to change directories without selecting a file. 3 Nov 2002. DWF. Fixed a problem with widget resizing with the help of Bob Portman that had plagued me from the beginning. Thanks, Bob! 5 August 2003. DWF Added TEXTSELECT method. 5 Aug 2003. DWF. Had to add FORWARD_FUNCTION statement to get error handler compiled when using DIRECTORY keyword. 24 Nov 2003. DWF. Fixed a problem with too many events going to an event handler specified with the EVENT_PRO or EVENT_FUNC keyword from the text widget. Now only Carriage Return events are passed on to the user-specified event handler. 8 July 2004. DWF. Replace all "\" characters with "/" characters in directory names. 8 Januay 2006. DWF. Set the default fonts to be the current widget font, rather than the default widget font. 4 Oct 2008. DWF.
(See $IDLUTILS_DIR/goddard/pro/coyote/fsc_fileselect.pro)
FSC_PLOTWINDOW
NAME: FSC_PLOTWINDOW PURPOSE: The purpose of this compound widget is to create a resizeable "plot window" inside a larger "page window". I'm not sure it has any value except as a utility routine for the PostScript configuration object FSC_PSCONFIG__DEFINE, but it's a neat program anyway. :-) AUTHOR: FANNING SOFTWARE CONSULTING David Fanning, Ph.D. 1645 Sheely Drive Fort Collins, CO 80526 USA Phone: 970-221-0438 E-mail: david@idlcoyote.com Coyote's Guide to IDL Programming: http://www.idlcoyote.com/ CATEGORY: Utility routine for FSC_PSCONFIG__DEFINE. CALLING SEQUENCE: plotwindowObject = CW_PlotWindow(parent) REQUIRED INPUT PARAMETERS: parent - The parent base widget of this compound widget. RETURN VALUE: plotwindowObject - The object reference of the compound widget. KEYWORDS: COLOR - If set, display the window in "color". This is the default on 24-bit devices. DEBUG - Set this keyword to turn traceback error handling on in the error handling code. EVENT_PRO - The event procedure for the widget. Required for events to be generated. Otherwise, all events are handled internally. LANDSCAPE - If set, display the page in landscape mode. Otherwise the page is display in portrait mode. PAGESIZE - The "pagesize" of the widget. Possible values are: "LETTER", "LEDGER", "LEGAL", "A4", and "DISPLAY". UNITS - A string indicating INCHES or CENTIMETER units. DEVICE units represented by a null string, "". UVALUE - A user value for the caller of this program. WINDOWCOLOR - A three-element array specifying the background window color (RGB). WINDOWSIZE - The size of the "window" on the page. A four-element array of normalized coordinates in the form [x0, y0, x1, y1]. EVENT STRUCTURE: The event structure that is returned from this compound widget is defined like this, where the sizes and offsets locate the target "window" on the page in normalized units: event = {ID:0L, TOP:0L, HANDLER:0L, XSize:0.0, YSize:0.0, XOffset:0.0, YOffset:0.0} MODIFICATIONS: Written by David Fanning, 31 January 2000. Fixed a small bug that prevented it working on Macintosh computers. 26 Sept 2000. DWF. Added a "DISPLAY" page size, so the program can be used to position plots and other graphics in a display window. The "page area" will have the same aspect ratio is the current graphics window. 17 March 2001. DWF. Changed some of the tolerances for "closeness" from 0.1 to 0.025 to allow smaller sizing for colorbars and other small objects. 6 July 2005. DWF.
(See $IDLUTILS_DIR/goddard/pro/coyote/fsc_plotwindow.pro)
FSC_PSCONFIG__DEFINE
NAME: FSC_PSCONFIG__DEFINE PURPOSE: The purpose of this program is to implement an object that can keep track of--and allow the user to change--the current configuration of the PostScript device. AUTHOR: FANNING SOFTWARE CONSULTING David Fanning, Ph.D. 1645 Sheely Drive Fort Collins, CO 80526 USA Phone: 970-221-0438 E-mail: david@idlcoyote.com Coyote's Guide to IDL Programming: http://www.idlcoyote.com/ CATEGORY: General programming. DOCUMENTATION: Complete documentation for the FSC_PSCONFIG object, including keyword and method descriptions, and example programs using the object can be found on the Coyote's Guide to IDL Programming web page: http://www.idlcoyote.com/programs/docs/fsc_psconfig.html Or, if you would prefer, you can download a self-contained PDF file: http://www.idlcoyote.com/programs/docs/fsc_psconfig.pdf KEYWORDS: Any keyword accepted by the FSC_PSCONFIG object can be used with this program. Here are a few of the most popular keywords. Bits_per_Pixel - The number of image bits saved for each image pixel: 2, 4, or 8. The default is 8. Color - Set this keyword to select Color PostScript output. Turned on by default. Decomposed - Set this keyword to 0 to select indexed color and to 1 to select decomposed color. DefaultSetup - Set this keyword to the "name" of a default style. Current styles (you can easily create and add your own to the source code) are the following: "System (Portrait)" - The normal "default" system set-up. Also, "System". "System (Landscape)" - The normal "default" landscape system set-up. "Centered (Portrait)" - The window centered on the page. Also, "Center" or "Centered". "Centered (Landscape)" - The window centered on the landscape page. Also, "Landscape". "Square (Portrait)" - A square plot, centered on the page. "Square (Landscape)" - A square plot, centered on the landscape page. "Figure (Small)" - A small encapsulated figure size, centered on page. Also, "Encapsulated" or "Encapsulate". "Figure (Large)" - A larger encapsulated figure size, centered on page. Also, "Figure". "Color (Portrait)" - A "centered" plot, with color turned on. Also, "Color". "Color (Landscape)" - A "centered" landscape plot, with color turned on. Directory - Set this keyword to the name of the starting directory. The current directory is used by default. Encapsulated - Set this keyword to select Encapsulated PostScript output. Turned off by default. European - This keyword has been depreciated in favor of METRIC. Filename - Set thie keyword to the name of the PostScript file. The default is "idl.ps". Inches - Set this keyword to indicate sizes and offsets are in inches as opposed to centimeters. Set by Metric keyword by default. Landscape - Set this keyword to select Landscape page output. Portrait page output is the default. Language_Level - Set this keyword to select the Language Level interpreter. Default is 1. Metric - Set this keyword to indicate metric mode (i.e., A4 page and centimeter units). Turned off by default. PageType - Set this keyword to the "type" of page. Possible values are: "Letter" - 8.5 by 11 inches. (Default, unless the Metric keyword is set.) "Legal" - 8.5 by 14 inches. "Ledger" - 11 by 17 inches. "A4" - 21.0 by 29.7 centimeters. (Default, if the Metric keyword is set.) XOffset - Set this keyword to the X Offset. Uses "System (Portrait)" defaults. (Note: offset calculated from lower-left corner of page.) XSize - Set this keyword to the X size of the PostScript "window". Uses "System (Portrait)" defaults. YOffset - Set this keyword to the Y Offset. Uses "System (Portrait)" defaults. (Note: offset calculated from lower-left corner of page.) YSize - Set this keyword to the Y size of the PostScript "window". Uses "System (Portrait)" defaults. In addition, the following keywords can be used: CANCEL -- An output keyword that will be set to 1 if the user chooses the Cancel button on the form. It will be 0 otherwise. FONTINFO -- Set this keyword is you wish to have font information appear on the form. The default is to not include font information. FONTTYPE -- Set this keyword to a named variable that will indicate the user's preference for font type. Values will be -1 (Hershey fonts), 0 (hardware fonts), and 1 (true-type fonts). This keyword will always return -1 unless the FONTINFO keyword has also been set. GROUP_LEADER -- Set this keyword to a widget identifier of the widget you wish to be a group leader for this program. EXAMPLE: A simple sequence of using the object would look something like this: psObject = Obj_New("FSC_PSCONFIG") psObject->GUI psKeywords = psObject->GetKeywords() thisDevice = !D.Name Set_Plot, 'PS' Device, _Extra=psKeywords cgImage, image Device, /Close_File Set_Plot, thisDevice Obj_Destroy, psObject Note that the object can also be called from the PS_CONFIG interface: psKeywords = PSConfig() OTHER PROGRAMS NEEDED: The following programs are required to run this one: fsc_droplist.pro fsc_fileselect.pro fsc_field.pro fsc_plotwindow MODIFICATIONS: Written by David W. Fanning, 31 January 2000. Added capability to call GUI methods when the current graphics device doesn't support windows. Device is restored when the GUI exits. 11 May 2000. DWF. Changed the default value for the Color keyword to 1. 16 May 2000. DWF. Fixed a bug where filename changed when switching Setups. 8 AUG 2000. DWF. Fixed a bug when saving setup in Landscape mode. 8 AUG 2000. DWF. Added the ability to Get and Set the object's name via the SetProperty and a very abbreviated GetProperty method. Also added a GetName method. 26 SEP 2000. DWF. Fixed a problem in which the proper configuration was not restored if in Landscape mode. 20 Nov 2000. DWF. Made a number of modifications at the request of Martin Schultz. 4 Dec 2000. DWF. Fixed a bug when setting file and directory names with the SetProperty method. 18 Dec 2000. DWF. Fixed a small problem in initializing the page size properly. 3 Jan 2001. DWF. Corrected a problem that resulted from a change to FSC_DROPLIST. 6 Jan 2001. DWF. Added the ability to restore the font type instead of always reverting to !P.Font. 7 Jan 2001. DWF. Increased the length of the file/directory name fields. 7 Jan 2001. DWF. Fixed another problem with Landscape mode interacting with A4 paper size. 7 Jan 2001. DWF. Seems I only half fixed the previous problem. :-( 26 April 2001. DWF. Forgot to update program to reflect change in FSC_FIELD. Fixed 26 April 2001. DWF. Changed BOOKMAN keyword to BKMAN to avoid conflict with BOOKSTYLE keyword. 26 April 2001. DWF. Modified the System Defaults to say "None" if none is used. Improved documentation. 10 September 2001. DWF. Added the ability to specify a filename at the same time as a Default Setup. 10 September 2001. DWF. Fixed a small problem in not setting new page sizes appropriately. 22 May 2002. DWF. Fixed a problem that occurred when the Accept button was not named "Accept". 6 May 2003.DWF. Whoops! I was a bit overly agressive on that last fix. :-( 17 July 2003. DWF. Fixed a problem with setting page types when using the DEFAULTSETUP keyword. 31 July 2003. DWF. Fixed a problem with turning encapsulation on in the GUI. Renamed ENCAPSULATE keyword ENCAPSULATED to avoid obvious errors. 31 July 2003. DWF. Removed obsolete STR_SEP and replaced with STRSPLIT. 27 Oct 2004. DWF. Now honoring EUROPEAN keyword when setting system default setups in the INIT method. 12 Nov 2004. DWF. Added CMYK output option 24 August 2007. Assumes LANGUAGE_LEVEL=2 printer. L. Anderson. Fixed a problem with the filename on WINDOWS computers coming back with forward slashes instead of backward slashes. 20 May 2008. DWF. Modified the program to return as the default, ISOLATIN1=1. 18 July 2008. DWF. Fixed a problem with filenames when a DEFAULTSETUP was used with it. 12 Nov 2008. DWF. Changed default window size when LANDSCAPE keyword is set. 10 April 2009. DWF. Changed the default window size for PORTRAIT mode to be a bit larger. 10 April 2009. DWF. Updated for IDL 7.1 and 24-bit color PostScript support. 24 May 2009. DWF. Added PAGETYPE field to returned structure to allow PostScript page type to be determined. 8 August 2009. DWF. Fixed a problem with 24-bit color support that allowed only IDL 7 versions to work correctly. 20 Sept 2009. DWF. Added a LANGUAGE_LEVEL keyword. 13 Dec 2010. DWF. Added the FONTYPE value to the keyword return structure. 14 Dec 2010. DWF. Modified the return structure to turn landscape mode off and set offsets to zero if in encapsulated mode. 19 Feb 2011. DWF. Changes to handle inability to create raster files from PS encapsulated files in landscape mode. Also removed changes of 19 Feb 2011 as no longer needed. 26 Aug 2011. DWF. The PAGETYPE was not getting set properly in the return keywords when the Metric option was selected on the GUI. 12 October 2011. DWF. The program now remembers the last directory you used and will start in that directory, unless told otherwise. 26 Oct 2011. DWF. Parsing of full filename failing. Fixed 27 Oct 2011. DWF.
(See $IDLUTILS_DIR/goddard/pro/coyote/fsc_psconfig__define.pro)
FSC_PS_SETUP__DEFINE
NAME: FSC_PS_SETUP__DEFINE PURPOSE: The purpose of FSC_PS_SETUP__DEFINE is to define a structure that is use with PS_START and PS_END, programs that make it easy to set-up for and close a PostScript file. The programs work in close conjunction with PSCONFIG, another program from the Coyote Library. AUTHOR: FANNING SOFTWARE CONSULTING David Fanning, Ph.D. 1645 Sheely Drive Fort Collins, CO 80526 USA Phone: 970-221-0438 E-mail: david@idlcoyote.com Coyote's Guide to IDL Programming: http://www.idlcoyote.com/ CATEGORY: Graphics, File Output, PostScript CALLING SEQUENCE: Used internally in PS_START and PS_END. COMMON BLOCKS: _$FSC_PS_START_ Contains the PS_STRUCT structure for communication between PS_START and PS_END. MODIFICATION HISTORY: Separated from PS_START file, 7 April 2009, by David W. Fanning. Added PAGETYPE field to structure. 8 August 2009. DWF. Changes to handle inability to create raster files from PS encapsulated files in landscape mode. Added "encapsulated" field to structure. 26 Aug 2011. DWF.
(See $IDLUTILS_DIR/goddard/pro/coyote/fsc_ps_setup__define.pro)
FTAB_DELROW
NAME: FTAB_DELROW PURPOSE: Delete rows of data from a FITS ASCII or binary table extension CALLING SEQUENCE: ftab_delrow, filename, rows, EXTEN_NO =, NEWFILE = ] INPUTS-OUPUTS filename - scalar string giving name of the FITS file containing an ASCII or binary table extension. rows - scalar or vector, specifying the row numbers to delete First row has index 0. If a vector, it will be sorted and duplicates will be removed OPTIONAL KEYWORD INPUTS: EXTEN_NO - scalar integer specifying which extension number to process Default is to process the first extension NEWFILE - scalar string specifying the name of the new output FITS file FTAB_DELROW will prompt for this parameter if not supplied EXAMPLE: Compress the first extension of a FITS file 'test.fits' to include only non-negative values in the 'FLUX' column ftab_ext,'test.fits','flux',flux ;Obtain original flux vector bad = where(flux lt 0) ;Find negative fluxes ftab_delrow,'test.fits',bad,new='test1.fits' ;Delete specified rows RESTRICTIONS: Does not work for variable length binary tables PROCEDURES USED: FITS_CLOSE, FITS_OPEN, FITS_READ, FITS_WRITE, FTDELROW, TBDELROW REVISION HISTORY: Written W. Landsman STX Co. August, 1997 Converted to IDL V5.0 W. Landsman September 1997 Use COPY_LUN if V5.6 or later W. Landsman February 2003 Assume since V5.6, COPY_LUN available W. Landsman Sep 2006
(See $IDLUTILS_DIR/goddard/pro/fits_table/ftab_delrow.pro)
FTAB_EXT
NAME: FTAB_EXT PURPOSE: Routine to extract columns from a FITS (binary or ASCII) table. CALLING SEQUENCE: FTAB_EXT, name_or_fcb, columns, v1, [v2,..,v9, ROWS=, EXTEN_NO= ] INPUTS: name_or_fcb - either a scalar string giving the name of a FITS file containing a (binary or ASCII) table, or an IDL structure containing as file control block (FCB) returned by FITS_OPEN If FTAB_EXT is to be called repeatedly on the same file, then it is quicker to first open the file with FITS_OPEN, and then pass the FCB structure to FTAB_EXT columns - table columns to extract. Can be either (1) String with names separated by commas (2) Scalar or vector of column numbers OUTPUTS: v1,...,v30 - values for the columns. Up to 30 columns can be extracted OPTIONAL INPUT KEYWORDS: ROWS - scalar or vector giving row number(s) to extract Row numbers start at 0. If not supplied or set to -1 then values for all rows are returned EXTEN_NO - Extension number to process. If not set, then data is extracted from the first extension in the file (EXTEN_NO=1) EXAMPLES: Read wavelength and flux vectors from the first extension of a FITS file, 'spec.fit'. Using FTAB_HELP,'spec.fit' we find that this information is in columns named 'WAVELENGTH' and 'FLUX' (in columns 1 and 2). To read the data IDL> ftab_ext,'spec.fit','wavelength,flux',w,f or IDL> ftab_ext,'spec.fit',[1,2],w,f PROCEDURES CALLED: FITS_READ, FITS_CLOSE, FTINFO, FTGET(), TBINFO, TBGET() HISTORY: version 1 W. Landsman August 1997 Converted to IDL V5.0 W. Landsman September 1997 Improve speed processing binary tables W. Landsman March 2000 Use new FTINFO calling sequence W. Landsman May 2000 Don't call fits_close if fcb supplied W. Landsman May 2001 Use STRSPLIT to parse column string W. Landsman July 2002 Cleanup pointers in TBINFO structure W. Landsman November 2003 Avoid EXECUTE() if V6.1 or later W. Landsamn December 2006 Assume since V6.1 W. Landsman June 2009 Read up to 30 columns W.L. Aug 2009
(See $IDLUTILS_DIR/goddard/pro/fits_table/ftab_ext.pro)
FTAB_HELP
NAME: FTAB_HELP PURPOSE: Describe the columns of a FITS binary or ASCII table extension(s). CALLING SEQUENCE: FTAB_HELP, filename, [ EXTEN_No = , TEXTOUT= ] or FTAB_HELP, fcb, [EXTEN_No=, TEXTOUT= ] INPUTS: filename - scalar string giving name of the FITS file. fcb - FITS control block returned by a previous call to FITS_OPEN OPTIONAL KEYWORD INPUTS: EXTEN_NO - integer scalar or vector specifying which FITS extensions to display. Default is to display all FITS extension. TEXTOUT - scalar number (0-7) or string (file name) determining output device (see TEXTOPEN). Default is TEXTOUT=1, output to the user's terminal EXAMPLE: Describe the columns in the second and fourth extensions of a FITS file spec.fits and write the results to a file 'spec24.lis' IDL> ftab_help,'spec.fits',exten=[2,4],t='spec24.lis' SYSTEM VARIABLES: Uses the non-standard system variables !TEXTOUT and !TEXTUNIT which must be defined (e.g. with ASTROLIB) before compilation NOTES: The behavior of FTAB_HELP was changed in August 2005 to display all extensions by default, rather than just the first extension PROCEDURES USED: FITS_READ, FITS_CLOSE, FITS_OPEN, FTHELP, TBHELP, TEXTOPEN, TEXTCLOSE HISTORY: version 1 W. Landsman August 1997 Corrected documentation W. Landsman September 1997 Don't call fits_close if fcb supplied W. Landsman May 2001 Default now is to display all extensions, EXTEN keyword can now be a vector W. Landsman Aug 2005
(See $IDLUTILS_DIR/goddard/pro/fits_table/ftab_help.pro)
FTAB_PRINT
NAME: FTAB_PRINT PURPOSE: Print the contents of a FITS (binary or ASCII) table extension. EXPLANATION: User can specify which rows or columns to print CALLING SEQUENCE: FTAB_PRINT, filename, columns, rows, [ TEXTOUT=, FMT=, EXTEN_NO= NUM_HEADER_LINES ] INPUTS: filename - scalar string giving name of a FITS file containing a binary or ASCII table columns - string giving column names, or vector giving column numbers (beginning with 1). If a string supplied then column names should be separated by comma's. if not supplied, then all columns are printed. If set to '*' then all columns are printed in table format (1 row per line, binary tables only). rows - (optional) vector of row numbers to print (beginning with 0). If not supplied or set to scalar, -1, then all rows are printed. OPTIONAL KEYWORD INPUT: EXTEN_NO - Extension number to read. If not set, then the first extension is printed (EXTEN_NO=1) FMT = Format string for print display (binary tables only). If not supplied, then any formats in the TDISP keyword fields will be used, otherwise IDL default formats. For ASCII tables, the format used is always as stored in the FITS table. NUM_HEADER_LINES - Number of lines to display the column headers (default = 1). By setting NUM_HEADER_LINES to an integer larger than 1, one can avoid truncation of the headers. In addition, setting NUM_HEADER_LINES will display commented lines indicating a FORMAT for reading the data, and a suggested call to readfmt.pro. Works for binary tables only NVAL_PER_LINE - The maximum number of values displayed from a multivalued column when printing in table format. Default = 6 TEXTOUT - scalar number (0-7) or string (file name) determining output device (see TEXTOPEN). Default is TEXTOUT=1, output to the user's terminal EXAMPLE: (1) Print all rows of the first 5 columns of the first extension of the file 'wfpc.fits' IDL> ftab_print,'vizier.fits',indgen(5)+1 (2) Print all columns of the first row to a file 'vizier.dat' in 'table' format IDL> ftab_print,'vizier.fits',t='vizier.dat','*',0 SYSTEM VARIABLES: Uses the non-standard system variables !TEXTOUT and !TEXTUNIT which must be defined (e.g. with ASTROLIB) prior to compilation. PROCEDURES USED: FITS_CLOSE, FITS_OPEN, FITS_READ, FTPRINT, TBPRINT HISTORY: version 1 W. Landsman August 1997 Check whether data exists W. Landsman Feb 2007 Check whether extension exists W. Landsman Mar 2010 Added NUM_HEADER_LINES, NVAL_PER_LINE keywords for binary tables W. Landsman Apr 2010
(See $IDLUTILS_DIR/goddard/pro/fits_table/ftab_print.pro)
FTADDCOL
NAME: FTADDCOL PURPOSE: Routine to add a field to a FITS ASCII table CALLING SEQUENCE: ftaddcol, h, tab, name, idltype, [ tform, tunit, tscal, tzero, tnull ] INPUTS: h - FITS table header. It will be updated as appropriate tab - FITS table array. Number of columns will be increased if neccessary. name - field name, scalar string idltype - idl data type (as returned by SIZE function) for field, For string data (type=7) use minus the string length. OPTIONAL INPUTS: tform - format specification 'qww.dd' where q = A, I, E, or D tunit - string giving physical units for the column. tscal - scale factor tzero - zero point for field tnull - null value for field Use '' as the value of tform,tunit,tscal,tzero,tnull if you want the default or no specification of them in the table header. OUTPUTS: h,tab - updated to allow new column of data PROCEDURES USED: FTINFO, FTSIZE, GETTOK(), SXADDPAR HISTORY: version 1 D. Lindler July, 1987 Converted to IDL V5.0 W. Landsman September 1997 Updated call to new FTINFO W. Landsman April 2000
(See $IDLUTILS_DIR/goddard/pro/fits_table/ftaddcol.pro)
FTCREATE
NAME: FTCREATE PURPOSE: Create a new (blank) FITS ASCII table and header with specified size. CALLING SEQUENCE: ftcreate, maxcols, maxrows, h, tab INPUTS: maxcols - number of character columns allocated, integer scalar maxrows - maximum number of rows allocated, integer scalar OUTPUTS: h - minimal FITS Table extension header, string array OPTIONAL OUTPUT: tab - empty table, byte array HISTORY: version 1 D. Lindler July. 87 Converted to IDL V5.0 W. Landsman September 1997 Make table creation optional, allow 1 row table, add comments to required FITS keywords W. Landsman October 2001
(See $IDLUTILS_DIR/goddard/pro/fits_table/ftcreate.pro)
FTDELCOL
NAME: FTDELCOL PURPOSE: Delete a column of data from a FITS table CALLING SEQUENCE: ftdelcol, h, tab, name INPUTS-OUPUTS h,tab - FITS 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: Suppose it has been determined that the F7.2 format used for a field FLUX in a FITS table is insufficient. The old column must first be deleted before a new column can be written with a new format. flux = FTGET(h,tab,'FLUX') ;Save the existing values FTDELCOL,h,tab,'FLUX' ;Delete the existing column FTADDCOL,h,tab,'FLUX',8,'F9.2' ;Create a new column with larger format FTPUT,h,tab,'FLUX',0,flux ;Put back the original values REVISION HISTORY: Written W. Landsman STX Co. August, 1988 Adapted for IDL Version 2, J. Isensee, July, 1990 Converted to IDL V5.0 W. Landsman September 1997 Updated call to new FTINFO W. Landsman May 2000
(See $IDLUTILS_DIR/goddard/pro/fits_table/ftdelcol.pro)
FTDELROW
NAME: FTDELROW PURPOSE: Delete a row of data from a FITS table CALLING SEQUENCE: ftdelrow, h, tab, rows INPUTS-OUPUTS h,tab - FITS 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 This vector will be sorted and duplicates removed by FTDELROW EXAMPLE: Compress a table to include only non-negative flux values flux = FTGET(h,tab,'FLUX') ;Obtain original flux vector bad = where(flux lt 0) ;Find negative fluxes FTDELROW,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. PROCEDURES USED: sxaddpar 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 Assume since V5.4, use BREAK instead of GOTO W. Landsman April 2006
(See $IDLUTILS_DIR/goddard/pro/fits_table/ftdelrow.pro)
FTGET
NAME: FTGET PURPOSE: Function to return value(s) from specified column in a FITS ASCII table CALLING SEQUENCE values = FTGET( h, tab, field, [ rows, nulls ] ) or values = FTGET( ft_str, tab, field. [rows, nulls] INPUTS: h - FITS ASCII extension header (e.g. as returned by FITS_READ) or ft_str - FITS table structure extracted from FITS header by FTINFO Use of the IDL structure will improve processing speed tab - FITS ASCII table array (e.g. as returned by FITS_READ) field - field name or number 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 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. 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 (ASCII table) extension of a FITS file 'spectra.fit' IDL> fits_read,'spectra.fit',tab,htab,exten=2 ;Read 2nd extension IDL> w = ftget( htab, tab,'wavelength') ;Wavelength vector IDL> f = ftget( htab, tab,'flux') ;Flux vector Slightly more efficient would be to first call FTINFO IDL> ftinfo, htab, ft_str ;Extract structure IDL> w = ftget(ft_str, tab,'wavelength') ;Wavelength vector IDL> f = ftget(ft_str, tab,'flux') ;Flux vector NOTES: (1) Use the higher-level procedure FTAB_EXT to extract vectors directly from the FITS file. (2) Use FTAB_HELP or FTHELP to determine the columns in a particular ASCII table. HISTORY: coded by D. Lindler July, 1987 Always check for null values W. Landsman August 1990 More informative error message W. Landsman Feb. 1996 Converted to IDL V5.0 W. Landsman September 1997 Allow structure rather than FITS header W. Landsman May 2000 No case sensitivity in TTYPE name W. Landsman February 2002
(See $IDLUTILS_DIR/goddard/pro/fits_table/ftget.pro)
FTHELP
NAME: FTHELP PURPOSE: Routine to print a description of a FITS ASCII table extension CALLING SEQUENCE: FTHELP, H, [ TEXTOUT = ] INPUTS: H - FITS header for ASCII table extension, string array OPTIONAL INPUT KEYWORD TEXTOUT - scalar number (0-7) or string (file name) determining output device (see TEXTOPEN). Default is TEXTOUT=1, output to the user's terminal NOTES: FTHELP checks that the keyword XTENSION equals 'TABLE' in the FITS header. SYSTEM VARIABLES: Uses the non-standard system variables !TEXTOUT and !TEXTUNIT which must be defined (e.g. with ASTROLIB) prior to compilation. PROCEDURES USED: REMCHAR, SXPAR(), TEXTOPEN, TEXTCLOSE, ZPARCHECK HISTORY: version 1 W. Landsman Jan. 1988 Add TEXTOUT option, cleaner format W. Landsman September 1991 TTYPE value can be longer than 8 chars, W. Landsman August 1995 Remove calls to !ERR, some vectorization W. Landsman February 2000 Slightly more compact display W. Landsman August 2005
(See $IDLUTILS_DIR/goddard/pro/fits_table/fthelp.pro)
FTHMOD
NAME: FTHMOD PURPOSE: Procedure to modify header information for a specified field in a FITS table. CALLING SEQUENCE: fthmod, h, field, parameter, value INPUT: h - FITS header for the table field - field name or number parameter - string name of the parameter to modify. Choices include: TTYPE - field name TUNIT - physical units for field (eg. 'ANGSTROMS') TNULL - null value (string) for field, (eg. '***') TFORM - format specification for the field TSCAL - scale factor TZERO - zero offset User should be aware that the validity of the change is not checked. Unless you really know what you are doing, this routine should only be used to change field names, units, or another user specified parameter. value - new value for the parameter. Refer to the FITS table standards documentation for valid values. EXAMPLE: Change the units for a field name "FLUX" to "Janskys" in a FITS table header,h IDL> FTHMOD, h, 'FLUX', 'TUNIT','Janskys' METHOD: The header keyword <parameter><field number> is modified with the new value. HISTORY: version 1, D. Lindler July 1987 Converted to IDL V5.0 W. Landsman September 1997 Major rewrite to use new FTINFO call W. Landsman May 2000
(See $IDLUTILS_DIR/goddard/pro/fits_table/fthmod.pro)
FTINFO
NAME: FTINFO PURPOSE: Return an informational structure from a FITS ASCII table header. CALLING SEQUENCE: ftinfo,h,ft_str, [Count = ] INPUTS: h - FITS ASCII table header, string array OUTPUTS: ft_str - IDL structure with extracted info from the FITS ASCII table header. Tags include .tbcol - starting column position in bytes .width - width of the field in bytes .idltype - idltype of field. 7 - string, 4- real*4, 3-integer, 5-real*8 .tunit - string unit numbers .tscal - scale factor .tzero - zero point for field .tnull - null value for the field .tform - format for the field .ttype - field name OPTIONAL OUTPUT KEYWORD: Count - Integer scalar giving number of fields in the table PROCEDURES USED: GETTOK(), SXPAR() NOTES: This procedure underwent a major revision in May 2000, and **THE NEW CALLING SEQUENCE IS INCOMPATIBLE WITH THE OLD ONE ** HISTORY: D. Lindler July, 1987 Converted to IDL V5.0 W. Landsman September 1997 Major rewrite, return structure W. Landsman April 2000
(See $IDLUTILS_DIR/goddard/pro/fits_table/ftinfo.pro)
FTKEEPROW
NAME: FTKEEPROW PURPOSE: Subscripts (and reorders) a FITS table. A companion piece to FTDELROW. CALLING SEQUENCE: ftkeeprow, h, tab, subs INPUT PARAMETERS: h = FITS table header array tab = FITS table data array subs = subscript array of FITS table rows. Works like any other IDL subscript array (0 based, of course). OUTPUT PARAMETERS: h and tab are modified MODIFICATION HISTORY: Written by R. S. Hill, ST Sys. Corp., 2 May 1991. Converted to IDL V5.0 W. Landsman September 1997
(See $IDLUTILS_DIR/goddard/pro/fits_table/ftkeeprow.pro)
FTPRINT
NAME: FTPRINT PURPOSE: Procedure to print specified columns and rows of a FITS table CALLING SEQUENCE: FTPRINT, h, tab, columns, [ rows, TEXTOUT = ] INPUTS: h - Fits header for table, string array 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 controls the output device; see the procedure TEXTOPEN SYSTEM VARIABLES: Uses nonstandard system variables !TEXTOUT and !TEXTOPEN These will be defined (using ASTROLIB) if not already present. Set !TEXTOUT = 3 to direct output to a disk file. The system variable is overriden by the value of the keyword TEXTOUT EXAMPLES: ftprint,h,tab,'STAR ID,RA,DEC' ;print id,ra,dec for all stars ftprint,h,tab,[2,3,4],indgen(100) ;print columns 2-4 for ;first 100 stars ftprint,h,tab,text="stars.dat" ;Convert entire FITS table to ;an ASCII file named STARS.DAT PROCEDURES USED: FTSIZE, FTINFO, TEXTOPEN, TEXTCLOSE 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 New FTINFO calling sequence W. Landsman May 2000 Parse scalar string with STRSPLIT W. Landsman July 2002 Fix format display of row number W. Landsman March 2003 Fix format display of row number again W. Landsman May 2003
(See $IDLUTILS_DIR/goddard/pro/fits_table/ftprint.pro)
FTPUT
NAME: FTPUT PURPOSE: Procedure to add or update a field in an FITS ASCII table CALLING SEQUENCE: FTPUT, htab, tab, field, row, values, [ nulls ] INPUTS: htab - FITS ASCII table header string array tab - FITS ASCII table array (e.g. as read by READFITS) field - string field name or integer field number row - either a non-negative integer scalar giving starting row to update, or a non-negative integer vector specifying rows to update. FTPUT will append a new row to a table if the value of 'row' exceeds the number of rows in the tab array values - value(s) to add or update. If row is a vector then values must contain the same number of elements. OPTIONAL INPUT: nulls - null value flag of same length as values. It should be set to 1 at null value positions and 0 elsewhere. OUTPUTS: htab,tab will be updated as specified. EXAMPLE: One has a NAME and RA and Dec vectors for 500 stars with formats A6, F9.5 and F9.5 respectively. Write this information to an ASCII table named 'star.fits'. IDL> FTCREATE,24,500,h,tab ;Create table header and (empty) data IDL> FTADDCOL,h,tab,'RA',8,'F9.5','DEGREES' ;Explicity define the IDL> FTADDCOL,h,tab,'DEC',8,'F9.5','DEGREES' ;RA and Dec columns IDL> FTPUT,h,tab,'RA',0,ra ;Insert RA vector into table IDL> FTPUT,h,tab,'DEC',0,dec ;Insert DEC vector into table IDL> FTPUT, h,tab, 'NAME',0,name ;Insert NAME vector with default IDL> WRITEFITS,'stars.fits',tab,h ;Write to a file Note that (1) explicit formatting has been supplied for the (numeric) RA and Dec vectors, but was not needed for the NAME vector, (2) A width of 24 was supplied in FTCREATE based on the expected formats (6+9+9), though the FT* will adjust this value as necessary, and (3) WRITEFITS will create a minimal primary header NOTES: (1) If the specified field is not already in the table, then FTPUT will create a new column for that field using default formatting. However, FTADDCOL should be called prior to FTPUT for explicit formatting. PROCEDURES CALLED FTADDCOL, FTINFO, FTSIZE, SXADDPAR, SXPAR() HISTORY: version 1 D. Lindler July, 1987 Allow E format W. Landsman March 1992 Write in F format if E format will overflow April 1994 Update documentation W. Landsman January 1996 Allow 1 element vector W. Landsman March 1996 Adjust string length to maximum of input string array June 1997 Work for more than 32767 elements August 1997 Converted to IDL V5.0 W. Landsman September 1997 Updated call to the new FTINFO W. Landsman May 2000 Fix case where header does not have any columns yet W.Landsman Sep 2002 Assume since V5.2, omit fstring() call W. Landsman April 2006
(See $IDLUTILS_DIR/goddard/pro/fits_table/ftput.pro)
FTSIZE
NAME: FTSIZE PURPOSE: Procedure to return the size of a FITS ASCII table. CALLING SEQUENCE: ftsize,h,tab,ncols,rows,tfields,ncols_all,nrows_all, [ERRMSG = ] INPUTS: h - FITS ASCII table header, string array tab - FITS table array, 2-d byte 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 OPTIONAL OUTPUT KEYWORD: ERRMSG = If this keyword is present, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. HISTORY D. Lindler July, 1987 Fix for 1-row table, W. Landsman HSTX, June 1994 Converted to IDL V5.0 W. Landsman September 1997 Added ERRMSG keyword W. Landsman May 2000
(See $IDLUTILS_DIR/goddard/pro/fits_table/ftsize.pro)
FTSORT
NAME: FTSORT PURPOSE: Sort a FITS ASCII table according to a specified field CALLING SEQUENCE: FTSORT,h,tab,[field, REVERSE = ] ;Sort original table header and array or FTSORT,h,tab,hnew,tabnew,[field, REVERSE =] ;Create new sorted header INPUTS: H - FITS header (string array) TAB - FITS table (byte array) associated with H. If less than 4 parameters are supplied, then H and TAB will be updated to contain the sorted table OPTIONAL INPUTS: FIELD - Field name(s) or number(s) used to sort the entire table. If FIELD is a vector then the first element is used for the primary sort, the second element is used for the secondary sort, and so forth. (A secondary sort only takes effect when values in the primary sort field are equal.) Character fields are sorted using the ASCII collating sequence. If omitted, the user will be prompted for the field name. OPTIONAL OUTPUTS: HNEW,TABNEW - Header and table containing the sorted tables EXAMPLE: Sort a FITS ASCII table by the 'DECLINATION' field in descending order Assume that the table header htab, and array, tab, have already been read (e.g. with READFITS or FITS_READ): IDL> FTSORT, htab, tab,'DECLINATION',/REVERSE OPTIONAL INPUT KEYWORD: REVERSE - If set then the table is sorted in reverse order (maximum to minimum. If FIELD is a vector, then REVERSE can also be a vector. For example, REVERSE = [1,0] indicates that the primary sort should be in descending order, and the secondary sort should be in ascending order. EXAMPLE: SIDE EFFECTS: A HISTORY record is added to the table header. REVISION HISTORY: Written W. Landsman June, 1988 Converted to IDL V5.0 W. Landsman September 1997 New FTINFO calling sequence, added REVERSE keyword, allow secondary sorts W. Landsman May 2000
(See $IDLUTILS_DIR/goddard/pro/fits_table/ftsort.pro)
FXADDPAR
NAME: FXADDPAR Purpose : Add or modify a parameter in a FITS header array. Explanation : This version of FXADDPAR will write string values longer than 68 characters using the FITS continuation convention described at http://heasarc.gsfc.nasa.gov/docs/heasarc/ofwg/docs/ofwg_recomm/r13.html Use : FXADDPAR, HEADER, NAME, VALUE, COMMENT Inputs : HEADER = String array containing FITS header. The maximum string length must be equal to 80. If not defined, then FXADDPAR 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 is equal to either "COMMENT" or "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 unless the /NOLOGICAL keyword is set. If the value is a string and is "long" (more than 69 characters), then it may be continued over more than one line using the OGIP CONTINUE standard. Opt. Inputs : COMMENT = String field. The '/' is added by this routine. Added starting in position 31. If not supplied, or set equal to '' (the null string), then any previous comment field in the header for that keyword is retained (when found). Outputs : HEADER = Updated header array. Opt. Outputs: None. Keywords : 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. If not supplied, then the IDL default formatting is used, except that double precision is given a format of G19.12. /NOCONTINUE = By default, FXADDPAR will break strings longer than 68 characters into multiple lines using the continuation convention. If this keyword is set, then the line will instead be truncated to 68 characters. This was the default behaviour of FXADDPAR prior to December 1999. /NOLOGICAL = If set, then the values 'T' and 'F' are not interpreted as logical values, and are simply added without interpretation. ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL, e.g. ERRMSG = '' FXADDPAR, ERRMSG=ERRMSG, ... IF ERRMSG NE '' THEN ... Calls : DETABIFY(), FXPAR(), FXPARPOS() Common : None. Restrictions: Warning -- Parameters and names are not checked against valid FITS parameter names, values and types. The required FITS keywords SIMPLE (or XTENSION), BITPIX, NAXIS, NAXIS1, NAXIS2, etc., must be entered in order. The actual values of these keywords are not checked for legality and consistency, however. Side effects: All HISTORY records are inserted in order at the end of the header. All COMMENT records are also inserted in order at the end of the header, but before the HISTORY records. The BEFORE and AFTER keywords can override this. All records with no keyword (blank) are inserted in order at the end of the header, but before the COMMENT and HISTORY records. The BEFORE and AFTER keywords can override this. All other records are inserted before any of the HISTORY, COMMENT, or "blank" records. The BEFORE and AFTER keywords can override this. String values longer than 68 characters will be split into multiple lines using the OGIP CONTINUE convention, unless the /NOCONTINUE keyword is set. For a description of the CONTINUE convention see http://fits.gsfc.nasa.gov/registry/continue_keyword.html Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : William Thompson, Jan 1992, from SXADDPAR by D. Lindler and J. Isensee. Differences include: * LOCATION parameter replaced with keywords BEFORE and AFTER. * Support for COMMENT and "blank" FITS keywords. * Better support for standard FITS formatting of string and complex values. * Built-in knowledge of the proper position of required keywords in FITS (although not necessarily SDAS/Geis) primary headers, and in TABLE and BINTABLE extension headers. William Thompson, May 1992, fixed bug when extending length of header, and new record is COMMENT, HISTORY, or blank. Written : William Thompson, GSFC, January 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version 2, William Thompson, GSFC, 5 September 1997 Fixed bug replacing strings that contain "/" character--it interpreted the following characters as a comment. Version 3, Craig Markwardt, GSFC, December 1997 Allow long values to extend over multiple lines Version 4, D. Lindler, March 2000, modified to use capital E instead of a lower case e for exponential format. Version 4.1 W. Landsman April 2000, make user-supplied format uppercase Version 4.2 W. Landsman July 2002, positioning of EXTEND keyword Version 5, 23-April-2007, William Thompson, GSFC Version 6, 02-Aug-2007, WTT, bug fix for OGIP long lines Version 6.1, 10-Feb-2009, W. Landsman, increase default format precision Version 6.2 30-Sep-2009, W. Landsman, added /NOLOGICAL keyword Version : Version 6.2, 30-Sep-2009
(See $IDLUTILS_DIR/goddard/pro/fits_bintable/fxaddpar.pro)
FXBADDCOL
NAME: FXBADDCOL PURPOSE : Adds a column to a binary table extension. EXPLANATION : Modify a basic FITS binary table extension (BINTABLE) header array to define a column. USE : FXBADDCOL, INDEX, HEADER, ARRAY [, TTYPE [, COMMENT ]] INPUTS : HEADER = String array containing FITS extension header. ARRAY = IDL variable used to determine the data size and type associated with the column. If the column is defined as containing variable length arrays, then ARRAY must be of the maximum size to be stored in the column. Opt. Inputs : TTYPE = Column label. COMMENT = Comment for TTYPE Outputs : INDEX = Index (1-999) of the created column. HEADER = The header is modified to reflect the added column. Opt. Outputs: None. Keywords : VARIABLE= If set, then the column is defined to contain pointers to variable length arrays in the heap area. DCOMPLEX= If set, and ARRAY is complex, with the first dimension being two (real and imaginary parts), then the column is defined as double-precision complex (type "M"). This keyword is only needed prior to IDL Version 4.0, when the double double complex datatype was unavailable in IDL BIT = If passed, and ARRAY is of type byte, then the column is defined as containg bit mask arrays (type "X"), with the value of BIT being equal to the number of mask bits. LOGICAL = If set, and array is of type byte, then the column is defined as containing logical arrays (type "L"). NO_TDIM = If set, then the TDIMn keyword is not written out to the header. No TDIMn keywords are written for columns containing variable length arrays. TUNIT = If passed, then corresponding keyword is added to header. TSCAL = Same. TZERO = Same. TNULL = Same. TDISP = Same. TDMIN = Same. TDMAX = Same. TDESC = Same. TCUNI = Same. TROTA = Same. TRPIX = Same. TRVAL = Same. TDELT = Same. ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. In order to use this feature, ERRMSG must be defined first, e.g. ERRMSG = '' FXBADDCOL, ERRMSG=ERRMSG, ... IF ERRMSG NE '' THEN ... Calls : FXADDPAR, FXPAR Common : None. Restrictions: Warning: No checking is done of any of the parameters defining the values of optional FITS keywords. FXBHMAKE must first be called to initialize the header. If ARRAY is of type character, then it must be of the maximum length expected for this column. If a character string array, then the largest string in the array is used to determine the maximum length. The DCOMPLEX keyword is ignored if ARRAY is not double-precision. ARRAY must also have a first dimension of two representing the real and imaginary parts. The BIT and LOGICAL keywords are ignored if ARRAY is not of type byte. BIT takes precedence over LOGICAL. Side effects: If the data array is multidimensional, then a TDIM keyword is added to the header, unless either NO_TDIM or VARIABLE is set. No TDIMn keywords are written out for bit arrays (format 'X'), since the dimensions would refer to bits, not bytes. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : William Thompson, Jan 1992. W. Thompson, Feb 1992, changed from function to procedure. W. Thompson, Feb 1992, modified to support variable length arrays. Written : William Thompson, GSFC, January 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version 2, William Thompson, GSFC, 31 May 1994 Added ERRMSG keyword. Version 3, William Thompson, GSFC, 23 June 1994 Modified so that ERRMSG is not touched if not defined. Version 4, William Thompson, GSFC, 30 December 1994 Added keyword TCUNI. Version 5, Wayne Landsman, GSFC, 12 Aug 1997 Recognize double complex IDL datatype Version 6, Wayne Landsman, GSFC. C. Yamauchi (ISAS) 23 Feb 2006 Support 64bit integers Version 7, C. Markwardt, GSFC, Allow unsigned integers, which have special TSCAL/TZERO values. Feb 2009 Version 8, P.Broos (PSU), Wayne Landsman (GSFC) Mar 2010 Do *not* force TTYPE* keyword to uppercase Version : Version 8, Mar 2010
(See $IDLUTILS_DIR/goddard/pro/fits_bintable/fxbaddcol.pro)
FXBCLOSE
NAME: FXBCLOSE Purpose : Close a FITS binary table extension opened for read. Explanation : Closes a FITS binary table extension that had been opened for read by FXBOPEN. Use : FXBCLOSE, UNIT Inputs : UNIT = Logical unit number of the file. Opt. Inputs : None. Outputs : None. Opt. Outputs: None. Keywords : ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. In order to use this feature, ERRMSG must be defined first, e.g. ERRMSG = '' FXBCLOSE, ERRMSG=ERRMSG, ... IF ERRMSG NE '' THEN ... Calls : None. Common : Uses common block FXBINTABLE--see "fxbintable.pro" for more information. Restrictions: The file must have been opened with FXBOPEN. Side effects: None. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : W. Thompson, Feb. 1992. Written : William Thompson, GSFC, February 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version 2, William Thompson, GSFC, 21 June 1994 Added ERRMSG keyword. Version 3, William Thompson, GSFC, 23 June 1994 Modified so that ERRMSG is not touched if not defined. Version : Version 3, 23 June 1994 Converted to IDL V5.0 W. Landsman September 1997
(See $IDLUTILS_DIR/goddard/pro/fits_bintable/fxbclose.pro)
FXBCOLNUM()
NAME: FXBCOLNUM() Purpose : Returns a binary table column number. Explanation : Given a column specified either by number or name, this routine will return the appropriate column number. Use : Result = FXBCOLNUM( UNIT, COL ) Inputs : UNIT = Logical unit number corresponding to the file containing the binary table. COL = Column in the binary table, given either as a character string containing a column label (TTYPE), or as a numerical column index starting from column one. Opt. Inputs : None. Outputs : The result of the function is the number of the column specified, or zero if no column is found (when passed by name). Opt. Outputs: None. Keywords : ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. In order to use this feature, ERRMSG must be defined first, e.g. ERRMSG = '' Result = FXBCOLNUM( ERRMSG=ERRMSG, ... ) IF ERRMSG NE '' THEN ... Calls : None. Common : Uses common block FXBINTABLE--see "fxbintable.pro" for more information. Restrictions: The binary table file must have been opened with FXBOPEN. If COL is passed as a number, rather than as a name, then it must be consistent with the number of columns in the table. Side effects: None. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : None. Written : William Thompson, GSFC, 2 July 1993. Modified : Version 1, William Thompson, GSFC, 2 July 1993. Version 2, William Thompson, GSFC, 29 October 1993. Added error message for not finding column by name. Version 3, William Thompson, GSFC, 21 June 1994 Added ERRMSG keyword. Version 4, William Thompson, GSFC, 23 June 1994 Modified so that ERRMSG is not touched if not defined. Version : Version 4, 23 June 1994 Converted to IDL V5.0 W. Landsman September 1997
(See $IDLUTILS_DIR/goddard/pro/fits_bintable/fxbcolnum.pro)
FXBCREATE
NAME: FXBCREATE Purpose : Open a new binary table at the end of a FITS file. Explanation : Write a binary table extension header to the end of a disk FITS file, and leave it open to receive the data. The FITS file is opened, and the pointer is positioned just after the last 2880 byte record. Then the binary header is appended. Calls to FXBWRITE will append the binary data to this file, and then FXBFINISH will close the file. Use : FXBCREATE, UNIT, FILENAME, HEADER Inputs : FILENAME = Name of FITS file to be opened. HEADER = String array containing the FITS binary table extension header. Opt. Inputs : None. Outputs : UNIT = Logical unit number of the opened file. EXTENSION= Extension number of newly created extension. Opt. Outputs: None. Keywords : ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. In order to use this feature, ERRMSG must be defined first, e.g. ERRMSG = '' FXBCREATE, ERRMSG=ERRMSG, ... IF ERRMSG NE '' THEN ... Calls : FXADDPAR, FXBFINDLUN, FXBPARSE, FXFINDEND Common : Uses common block FXBINTABLE--see "fxbintable.pro" for more information. Restrictions: The primary FITS data unit must already be written to a file. The binary table extension header must already be defined (FXBHMAKE), and must match the data that will be written to the file. Side effects: None. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : W. Thompson, Jan 1992, based on WRITEFITS by J. Woffard and W. Landsman. W. Thompson, Feb 1992, changed from function to procedure. W. Thompson, Feb 1992, removed all references to temporary files. Written : William Thompson, GSFC, January 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version 2, William Thompson, GSFC, 21 July 1993. Fixed bug with variable length arrays. Version 3, William Thompson, GSFC, 21 June 1994 Added ERRMSG keyword. Version 4, William Thompson, GSFC, 23 June 1994 Modified so that ERRMSG is not touched if not defined. Version 5, Antony Bird, Southampton, 25 June 1997 Modified to allow very long tables Version : Version 5, 25 June 1997 Converted to IDL V5.0 W. Landsman September 1997 Added EXTENSION parameter, C. Markwardt 1999 Jul 15 More efficient zeroing of file, C. Markwardt, 26 Feb 2001 Recompute header size if updating THEAP keyword B. Roukema April 2010
(See $IDLUTILS_DIR/goddard/pro/fits_bintable/fxbcreate.pro)
FXBDIMEN()
NAME: FXBDIMEN() PURPOSE: Returns the dimensions for a column in a FITS binary table. Explanation : This procedure returns the dimensions associated with a column in a binary table opened for read with the command FXBOPEN. Use : Result = FXBDIMEN(UNIT,COL) Inputs : UNIT = Logical unit number returned by FXBOPEN routine. Must be a scalar integer. COL = Column in the binary table to read data from, either as a character string containing a column label (TTYPE), or as a numerical column index starting from column one. Opt. Inputs : None. Outputs : The result of the function is an array containing the dimensions for the specified column in the FITS binary table that UNIT points to. Opt. Outputs: None. Keywords : ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. In order to use this feature, ERRMSG must be defined first, e.g. ERRMSG = '' Result = FXBDIMEN( ERRMSG=ERRMSG, ... ) IF ERRMSG NE '' THEN ... Calls : FXBCOLNUM, FXBFINDLUN Common : Uses common block FXBINTABLE--see "fxbintable.pro" for more information. Restrictions: None. Side effects: The dimensions will be returned whether or not the table is still open or not. If UNIT does not point to a binary table, then 0 is returned. If UNIT is an undefined variable, then 0 is returned. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : None. Written : William Thompson, GSFC, 4 March 1994. Modified : Version 1, William Thompson, GSFC, 4 March 1994. Version 2, William Thompson, GSFC, 21 June 1994 Added ERRMSG keyword. Version 3, William Thompson, GSFC, 23 June 1994 Modified so that ERRMSG is not touched if not defined. Version : Version 3, 23 June 1994 Converted to IDL V5.0 W. Landsman September 1997
(See $IDLUTILS_DIR/goddard/pro/fits_bintable/fxbdimen.pro)
FXBFIND
NAME: FXBFIND Purpose : Find column keywords in a FITS binary table header. Explanation : Finds the value of a column keyword for all the columns in the binary table for which it is set. For example, FXBFIND, UNIT, 'TTYPE', COLUMNS, VALUES, N_FOUND Would find all instances of the keywords TTYPE1, TTYPE2, etc. The array COLUMNS would contain the column numbers for which a TTYPEn keyword was found, and VALUES would contain the values. N_FOUND would contain the total number of instances found. Use : FXBFIND, [UNIT or HEADER], KEYWORD, COLUMNS, VALUES, N_FOUND [, DEFAULT ] Inputs : Either UNIT or HEADER must be passed. UNIT = Logical unit number of file opened by FXBOPEN. HEADER = FITS binary table header. KEYWORD = Prefix to a series of FITS binary table column keywords. The keywords to be searched for are formed by combining this prefix with the numbers 1 through the value of TFIELDS in the header. Opt. Inputs : DEFAULT = Default value to use for any column keywords that aren't found. If passed, then COLUMNS and VALUES will contain entries for every column. Otherwise, COLUMNS and VALUES only contain entries for columns where values were found. Outputs : COLUMNS = Array containing the column numbers for which values of the requested keyword series were found. VALUES = Array containing the found values. N_FOUND = Number of values found. The value of this parameter is unaffected by whether or not DEFAULT is passed. Opt. Outputs: None. Output Keywords : COMMENTS = Comments associated with each keyword, if any Calls : FXBFINDLUN, FXPAR Common : Uses common block FXBINTABLE--see "fxbintable.pro" for more information. Restrictions: If UNIT is passed, then the file must have been opened with FXBOPEN. If HEADER is passed, then it must be a legal FITS binary table header. The type of DEFAULT must be consistent with the values of the requested keywords, i.e. both most be either of string or numerical type. The KEYWORD prefix must not have more than five characters to leave room for the three digits allowed for the column numbers. Side effects: None. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : William Thompson, Feb. 1992. Written : William Thompson, GSFC, February 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Vectorized implementation improves performance, CM 18 Nov 1999 Added COMMENTS keyword CM Nov 2003 Remove use of obsolete !ERR system variable W. Landsman April 2010 Fix error introduced April 2010 W. Landsman Version : Version 3, April 2010.
(See $IDLUTILS_DIR/goddard/pro/fits_bintable/fxbfind.pro)
FXBFINDLUN()
NAME: FXBFINDLUN() Purpose : Find logical unit number UNIT in FXBINTABLE common block. Explanation : Finds the proper index to use for getting information about the logical unit number UNIT in the arrays stored in the FXBINTABLE common block. Called from FXBCREATE and FXBOPEN. Use : Result = FXBFINDLUN( UNIT ) Inputs : UNIT = Logical unit number. Opt. Inputs : None. Outputs : The result of the function is an index into the FXBINTABLE common block. Opt. Outputs: None. Keywords : None. Calls : None. Common : Uses common block FXBINTABLE--see "fxbintable.pro" for more information. Restrictions: None. Side effects: If UNIT is not found in the common block, then it is added to the common block. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : William Thompson, Feb. 1992. Written : William Thompson, GSFC, February 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version 2, William Thompson, GSFC, 21 July 1993. Added DHEAP variable to fix bug with variable length arrays. Version 3, Michael Schubnell, University of Michigan, 22 May 1996 Change N_DIMS from short to long integer. Version : Version 3, 22 May 1996 Converted to IDL V5.0 W. Landsman September 1997 Make NAXIS1, NAXIS2, HEAP, DHEAP, BYTOFF 64-bit integers to deal with large files, E. Hivon Mar 2008
(See $IDLUTILS_DIR/goddard/pro/fits_bintable/fxbfindlun.pro)
FXBFINISH
NAME: FXBFINISH Purpose : Close a FITS binary table extension file opened for write. Explanation : Closes a FITS binary table extension file that had been opened for write by FXBCREATE. Use : FXBFINISH, UNIT Inputs : UNIT = Logical unit number of the file. Opt. Inputs : None. Outputs : None. Opt. Outputs: None. Keywords : ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. In order to use this feature, ERRMSG must be defined first, e.g. ERRMSG = '' FXBFINISH, ERRMSG=ERRMSG, ... IF ERRMSG NE '' THEN ... Calls : None. Common : Uses common block FXBINTABLE--see "fxbintable.pro" for more information. Restrictions: The file must have been opened with FXBCREATE, and written with FXBWRITE. Side effects: Any bytes needed to pad the file out to an integral multiple of 2880 bytes are written out to the file. Then, the file is closed. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : W. Thompson, Jan 1992. W. Thompson, Feb 1992, modified to support variable length arrays. W. Thompson, Feb 1992, removed all references to temporary files. Written : William Thompson, GSFC, January 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version 2, William Thompson, GSFC, 21 July 1993. Fixed bug with variable length arrays. Version 3, William Thompson, GSFC, 31 May 1994 Added ERRMSG keyword. Version 4, William Thompson, GSFC, 23 June 1994 Modified so that ERRMSG is not touched if not defined. Version : Version 4, 23 June 1994 Converted to IDL V5.0 W. Landsman September 1997
(See $IDLUTILS_DIR/goddard/pro/fits_bintable/fxbfinish.pro)
FXBGROW
NAME: FXBGROW PURPOSE : Increase the number of rows in a binary table. EXPLANATION : Call FXBGROW to increase the size of an already-existing FITS binary table. The number of rows increases to NROWS; however the table cannot shrink by this operation. This procedure is useful when a table with an unknown number of rows must be created. The caller would then call FXBCREATE to construct a table of some base size, and follow with calls to FXBGROW to lengthen the table as needed. The extension being enlarged need not be the last extension in the file. If subsequent extensions exist in the file, they will be shifted properly. CALLING SEQUENCE : FXBGROW, UNIT, HEADER, NROWS[, ERRMSG= , NOZERO= , BUFFERSIZE= ] INPUT PARAMETERS : UNIT = Logical unit number of an already-opened file. HEADER = String array containing the FITS binary table extension header. The header is modified in place. NROWS = New number of rows, always more than the previous number. OPTIONAL INPUT KEYWORDS: NOZERO = when set, FXBGROW will not zero-pad the new data if it doesn't have to. ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. In order to use this feature, ERRMSG must be defined first, e.g. ERRMSG = '' FXBGROW, ERRMSG=ERRMSG, ... IF ERRMSG NE '' THEN ... BUFFERSIZE = Size in bytes for intermediate data transfers (default 32768) Calls : FXADDPAR, FXHREAD, BLKSHIFT Common : Uses common block FXBINTABLE--see "fxbintable.pro" for more information. Restrictions: The file must be open with write permission. The binary table extension in question must already by written to the file (using FXBCREATE). A table can never shrink via this operation. SIDE EFFECTS: The FITS file will grow in size, and heap areas are preserved by moving them to the end of the file. The header is modified to reflect the new number of rows. CATEGORY : Data Handling, I/O, FITS, Generic. Initially written, C. Markwardt, GSFC, Nov 1998 Added ability to enlarge arbitrary extensions and tables with variable sized rows, not just the last extension in a file, CM, April 2000 Fix bug in the zeroing of the output file, C. Markwardt, April 2005
(See $IDLUTILS_DIR/goddard/pro/fits_bintable/fxbgrow.pro)
FXBHEADER()
NAME: FXBHEADER() PURPOSE: Returns the header of an open FITS binary table. EXPLANATION: This procedure returns the FITS extension header of a FITS binary table opened for read with the command FXBOPEN. Use : Result = FXBHEADER(UNIT) Inputs : UNIT = Logical unit number returned by FXBOPEN routine. Must be a scalar integer. Opt. Inputs : None. Outputs : The result of the function is a string array containing the header for the FITS binary table that UNIT points to. Opt. Outputs: None. Keywords : None. Calls : FXBFINDLUN Common : Uses common block FXBINTABLE--see "fxbintable.pro" for more information. Restrictions: None. Side effects: The string array returned always has as many elements as the largest header read by FXBOPEN. Any extra elements beyond the true header are blank or null strings. The header will be returned whether or not the table is still open or not. If UNIT does not point to a binary table, then a string array of nulls is returned. If UNIT is an undefined variable, then the null string is returned. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : None. Written : William Thompson, GSFC, 1 July 1993. Modified : Version 1, William Thompson, GSFC, 1 July 1993. Version : Version 1, 1 July 1993. Converted to IDL V5.0 W. Landsman September 1997
(See $IDLUTILS_DIR/goddard/pro/fits_bintable/fxbheader.pro)
FXBHELP
NAME: FXBHELP Purpose : Prints short description of columns in a FITS binary table. Explanation : Prints a short description of the columns in a FITS binary table to the terminal screen. Use : FXBHELP, UNIT Inputs : UNIT = Logical unit number of file opened by FXBOPEN. Opt. Inputs : None. Outputs : None. Opt. Outputs: None. Keywords : None. Calls : FXBFIND, FXBFINDLUN, FXPAR Common : Uses common block FXBINTABLE--see "fxbintable.pro" for more information. Restrictions: The file must have been opened with FXBOPEN. Side effects: Certain fields may be truncated in the display. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : William Thompson, Feb. 1992, from TBHELP by W. Landsman. Written : William Thompson, GSFC, February 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version 2, William Thompson, GSFC, 12 May 1993. Modified to not write to a logical unit number assigned to the terminal. This makes it compatible with IDL for Windows. Version 3, Wayne Landsman GSFC April 2010 Remove use of obsolete !ERR system variable Version : Version 3, April 2010.
(See $IDLUTILS_DIR/goddard/pro/fits_bintable/fxbhelp.pro)
FXBHMAKE
NAME: FXBHMAKE Purpose : Create basic FITS binary table extension (BINTABLE) header. Explanation : Creates a basic header array with all the required keywords, but with none of the table columns defined. This defines a basic structure which can then be added to or modified by other routines. Use : FXBHMAKE, HEADER, NROWS [, EXTNAME [, COMMENT ]] Inputs : NROWS = Number of rows in the binary table. Opt. Inputs : EXTNAME = If passed, then the EXTNAME record is added with this value. COMMENT = Comment to go along with EXTNAME. Outputs : HEADER = String array containing FITS extension header. Opt. Outputs: None. Keywords : INITIALIZE = If set, then the header is completely initialized, and any previous entries are lost. DATE = If set, then the DATE keyword is added to the header. EXTVER = Extension version number (integer). EXTLEVEL = Extension level number (integer). ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. In order to use this feature, ERRMSG must be defined first, e.g. ERRMSG = '' FXBHMAKE, ERRMSG=ERRMSG, ... IF ERRMSG NE '' THEN ... Calls : GET_DATE, FXADDPAR, FXHCLEAN Common : None. Restrictions: Warning: No checking is done of any of the parameters. Side effects: None. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : William Thompson, Jan 1992. William Thompson, Sep 1992, added EXTVER and EXTLEVEL keywords. Written : William Thompson, GSFC, January 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version 2, William Thompson, GSFC, 21 June 1994 Added ERRMSG keyword. Version 3, William Thompson, GSFC, 23 June 1994 Modified so that ERRMSG is not touched if not defined. Version : Version 3, 23 June 1994 Converted to IDL V5.0 W. Landsman September 1997
(See $IDLUTILS_DIR/goddard/pro/fits_bintable/fxbhmake.pro)
FXBINTABLE
NAME: FXBINTABLE Purpose : Common block FXBINTABLE used by "FXB" routines. Explanation : This is not an IDL routine as such, but contains the definition of the common block FXBINTABLE for inclusion into other routines. By defining the common block in one place, the problem of conflicting definitions is avoided. This file is included into routines that need this common block with the single line (left justified) @fxbintable FXBINTABLE contains the following arrays: LUN = An array of logical unit numbers of currently (or previously) opened binary table files. STATE = Array containing the state of the FITS files associated with the logical unit numbers, where 0=closed, 1=open for read, and 2=open for write. HEAD = FITS binary table headers. MHEADER = Array containing the positions of the first data byte of the header for each file referenced by array LUN. NHEADER = Array containing the positions of the first data byte after the header for each file referenced by array LUN. NAXIS1 = Values of NAXIS1 from the binary table headers. NAXIS2 = Values of NAXIS2 from the binary table headers. TFIELDS = Values of TFIELDS from the binary table headers. HEAP = The start of the first byte of the heap area for variable length arrays. DHEAP = The start of the first byte of the next variable length array, if writing. BYTOFF = Byte offset from the beginning of the row for each column in the binary table headers. TTYPE = Values of TTYPE for each column in the binary table headers. FORMAT = Character code formats of the various columns. IDLTYPE = IDL type code for each column in the binary table headers. N_ELEM = Number of elements for each column in the binary table headers. TSCAL = Scale factors for the individual columns. TZERO = Zero offsets for the individual columns. MAXVAL = For variable length arrays, contains the maximum number of elements for each column in the binary table headers. N_DIMS = Number of dimensions, and array of dimensions for each column of type string in the binary table headers. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : William Thompson, Feb 1992. Written : William Thompson, GSFC, February 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version 2, William Thompson, GSFC, 21 July 1993. Added DHEAP variable to fix bug with variable length arrays. Version : Version 2, 21 July 1993.
(See $IDLUTILS_DIR/goddard/pro/fits_bintable/fxbintable.pro)
FXBISOPEN()
NAME: FXBISOPEN() PURPOSE: Returns true if UNIT points to an open FITS binary table. Explanation : This procedure checks to see if the logical unit number given by the variable UNIT corresponds to a FITS binary table opened for read with the command FXBOPEN, and which has not yet been closed with FXBCLOSE. Use : Result = FXBISOPEN(UNIT) If FXBISOPEN(UNIT) THEN ... Inputs : UNIT = Logical unit number returned by FXBOPEN routine. Must be a scalar integer. Opt. Inputs : None. Outputs : The result of the function is either True (1) or False (0), depending on whether UNIT points to an open binary table or not. Opt. Outputs: None. Keywords : None. Calls : FXBFINDLUN Common : Uses common block FXBINTABLE--see "fxbintable.pro" for more information. Restrictions: None. Side effects: If UNIT is an undefined variable, then False (0) is returned. If UNIT points to a FITS binary table file that is opened for write, then False (0) is returned. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : None. Written : William Thompson, GSFC, 1 July 1993. Modified : Version 1, William Thompson, GSFC, 1 July 1993. Version : Version 1, 1 July 1993. Converted to IDL V5.0 W. Landsman September 1997
(See $IDLUTILS_DIR/goddard/pro/fits_bintable/fxbisopen.pro)
FXBOPEN
NAME: FXBOPEN Purpose : Open binary table extension in a disk FITS file for reading or updating Explanation : Opens a binary table extension in a disk FITS file for reading. The columns are then read using FXBREAD, and the file is closed when done with FXBCLOSE. Use : FXBOPEN, UNIT, FILENAME, EXTENSION [, HEADER ] Inputs : FILENAME = Name of FITS file to be opened. Optional extension *number* may be specified, in either of the following formats (using the FTOOLS convention): FILENAME[EXT] or FILENAME+EXT, where EXT is 1 or higher. Such an extension specification takes priority over EXTENSION. EXTENSION = Either the number of the FITS extension, starting with the first extension after the primary data unit being one; or a character string containing the value of EXTNAME to search for. Opt. Inputs : None. Outputs : UNIT = Logical unit number of the opened file. Opt. Outputs: HEADER = String array containing the FITS binary table extension header. Keywords : NO_TDIM = If set, then any TDIMn keywords found in the header are ignored. ACCESS = A scalar string describing access privileges as one of READ ('R') or UPDATE ('RW'). DEFAULT: 'R' REOPEN = If set, UNIT must be an already-opened file unit. FXBOPEN will treat the file as a FITS file. ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. In order to use this feature, ERRMSG must be defined first, e.g. ERRMSG = '' FXBOPEN, ERRMSG=ERRMSG, ... IF ERRMSG NE '' THEN ... Calls : FXBFINDLUN, FXBPARSE, FXHREAD, FXPAR Common : Uses common block FXBINTABLE--see "fxbintable.pro" for more information. Restrictions: The file must be a valid FITS file. Side effects: None. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : W. Thompson, Feb 1992, based on READFITS by J. Woffard and W. Landsman. W. Thompson, Feb 1992, changed from function to procedure. W. Thompson, June 1992, fixed up error handling. Written : William Thompson, GSFC, February 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version 2, William Thompson, GSFC, 27 May 1994 Added ERRMSG keyword. Version 3, William Thompson, GSFC, 21 June 1994 Extended ERRMSG to call to FXBPARSE Version 4, William Thompson, GSFC, 23 June 1994 Modified so that ERRMSG is not touched if not defined. Version 4, 23 June 1994 Added ACCESS, REOPEN keywords, and FXFILTER package, CM 1999 Feb 03 Added FILENAME[EXT] and FILENAME+EXT extension parsing, CM 1999 Jun 28 Some general tidying, CM 1999 Nov 18 Allow for possible 64bit integer number of bytes W. Landsman Nov 2007 Make Ndata a 64bit integer to deal with larger files, E. Hivon, Mar 2008
(See $IDLUTILS_DIR/goddard/pro/fits_bintable/fxbopen.pro)
FXBPARSE
NAME: FXBPARSE Purpose : Parse the binary table extension header. Explanation : Parses the binary table extension header, and store the information about the format of the binary table in the FXBINTABLE common block--called from FXBCREATE and FXBOPEN. Use : FXBPARSE, ILUN, UNIT, HEADER Inputs : ILUN = Index into the arrays in the FXBINTABLE common block. HEADER = FITS binary table extension header. Opt. Inputs : None. Outputs : None. Opt. Outputs: None. Keywords : NO_TDIM = If set, then any TDIMn keywords found in the header are ignored. ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. In order to use this feature, ERRMSG must be defined first, e.g. ERRMSG = '' FXBPARSE, ERRMSG=ERRMSG, ... IF ERRMSG NE '' THEN ... Calls : FXBFIND, FXBTDIM, FXBTFORM, FXPAR Common : Uses common block FXBINTABLE--see "fxbintable.pro" for more information. Restrictions: None. Side effects: Any TDIMn keywords found for bit arrays (format 'X') are ignored, since the dimensions would refer to bits, not bytes. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : William Thompson, Feb. 1992. William Thompson, Jan. 1993, modified for renamed FXBTFORM and FXBTDIM. Written : William Thompson, GSFC, February 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version 2, William Thompson, GSFC, 21 June 1994 Added ERRMSG keyword. Version 3, William Thompson, GSFC, 23 June 1994 Modified so that ERRMSG is not touched if not defined. Version 4, Michael Schubnell, University of Michigan, 22 May 1996 Change N_DIMS from short to long integer. Version 5, W. Landsman, GSFC, 12 Aug 1997 Use double complex datatype, if needed Version 6, W. Landsman GSFC 30 Aug 1997 Optimized FXPAR; call FXBFIND for speed, CM 1999 Nov 18 Modify DHEAP(ILUN) when opening table now, CM 2000 Feb 22 Default the TZERO/TSCAL tables to double instead of single precision floating point, CM 2003 Nov 23 Make NAXIS1 and NAXIS2 64-bit integers to deal with large files, E. Hivon Mar 2008 Remove use of Obsolete !ERR system variable Version Version 8 April 2010
(See $IDLUTILS_DIR/goddard/pro/fits_bintable/fxbparse.pro)
FXBREAD
NAME: FXBREAD Purpose : Read a data array from a disk FITS binary table file. Explanation : Each call to FXBREAD will read the data from one column and one row from the FITS data file, which should already have been opened by FXBOPEN. One needs to call this routine for every column and every row in the binary table. FXBCLOSE will then close the FITS data file. Use : FXBREAD, UNIT, DATA, COL [, ROW ] Inputs : UNIT = Logical unit number corresponding to the file containing the binary table. COL = Column in the binary table to read data from, either as a character string containing a column label (TTYPE), or as a numerical column index starting from column one. Opt. Inputs : ROW = Either row number in the binary table to read data from, starting from row one, or a two element array containing a range of row numbers to read. If not passed, then the entire column is read in. Row must be passed for variable length arrays. Outputs : DATA = IDL data array to be read from the file. Opt. Outputs: None. Keywords : NOSCALE = If set, then the output data will not be scaled using the optional TSCAL and TZERO keywords in the FITS header. Default is to scale. NOIEEE = If set, then the output data is not byte-swapped to machine order. NOIEEE implies NOSCALE. Default is to perform the byte-swap. VIRTUAL = If set, and COL is passed as a name rather than a number, then if the program can't find a column with that name, it will then look for a keyword with that name in the header. Such a keyword would then act as a "virtual column", with the same value for every row. DIMENSIONS = Vector array containing the dimensions to be used to read in the data. Bypasses any dimensioning information stored in the header. Ignored for bit arrays. If the data type is double-precision complex, then an extra dimension of 2 is prepended to the dimensions passed by the user. NANVALUE= Value signalling data dropout. All points corresponding to IEEE NaN (not-a-number) are converted to this number. Ignored unless DATA is of type float, double-precision or complex. ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. In order to use this feature, ERRMSG must be defined first, e.g. ERRMSG = '' FXBREAD, ERRMSG=ERRMSG, ... IF ERRMSG NE '' THEN ... Calls : FXPAR, WHERE_NEGZERO, WHERENAN Common : Uses common block FXBINTABLE--see "fxbintable.pro" for more information. Restrictions: The binary table file must have been opened with FXBOPEN. The data must be consistent with the column definition in the binary table header. The row number must be consistent with the number of rows stored in the binary table header. The number of elements implied by the dimensions keyword must not exceed the number of elements stored in the file. Side effects: If the DIMENSIONS keyword is used, then the number of data points read in may be less than the number of points stored in the table. If there are no elements to read in (the number of elements is zero), then the program sets !ERR to -1, and DATA is unmodified. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : W. Thompson, Jan 1992. W. Thompson, Feb 1992, modified to support variable length arrays. W. Thompson, Jun 1992, modified way that row ranges are read in. No longer works reiteratively. W. Thompson, Jun 1992, fixed bug where NANVALUE would be modified by TSCAL and TZERO keywords. W. Thompson, Jun 1992, fixed bug when reading character strings. Treats dimensions better when reading multiple rows. Written : William Thompson, GSFC, January 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version 2, William Thompson, GSFC, 30 June 1993. Added overwrite keyword to REFORM call to speed up. Version 3, William Thompson, GSFC, 21 July 1993. Fixed bug with variable length arrays. Version 4, William Thompson, GSFC, 29 October 1993. Added error message for not finding column by name. Version 5, William Thompson, GSFC, 31 May 1994 Added ERRMSG keyword. Version 6, William Thompson, GSFC, 23 June 1994 Modified so that ERRMSG is not touched if not defined. Version 7, William Thompson, GSFC, 29 December 1994 Fixed bug where single element dimensions were lost. Version 8, William Thompson, GSFC, 20 March 1995 Fixed bug introduced in version 7. Version 9, Wayne Landsman, GSFC, 3 July 1996 Fixed bug involving use of virtual keyword. Version 10, William Thompson, GSFC, 31-Jan-1997 Added call to WHERE_NEGZERO. Version 11, Wayne Landsman, GSFC, 12 Aug, 1997 Use IDL dcomplex datatype if needed Version 12, Wayne Landmsan, GSFC, 20 Feb, 1998 Remove call to WHERE_NEGZERO (now part of IEEE_TO_HOST) Version 13, 18 Nov 1999, CM, Add NOIEEE keyword Version 14, 21 Aug 2000, William Thompson, GSFC Catch I/O errors Version 15, W. Landsman GSFC 10 Dec 2009 Fix Dimension keyword, remove IEEE_TO_HOST Version : Version 15, 10 Dec 2009
(See $IDLUTILS_DIR/goddard/pro/fits_bintable/fxbread.pro)
FXBREADM
NAME: FXBREADM PURPOSE: Read multiple columns/rows from a disk FITS binary table file. EXPLANATION : A call to FXBREADM will read data from multiple rows and multiple columns in a single procedure call. Up to forty-nine columns may be read in a single pass; the number of rows is limited essentially by available memory. The file should have already been opened with FXBOPEN. FXBREADM optimizes reading multiple columns by first reading a large chunk of data from the FITS file directly, and then slicing the data into columns within memory. FXBREADM can read variable-length arrays (see below). The number of columns is limited to 49 if data are passed by positional argument. However, this limitation can be overcome by having FXBREADM return the data in an array of pointers. The user should set the PASS_METHOD keyword to 'POINTER', and an array of pointers to the data will be returned in the POINTERS keyword. The user is responsible for freeing the pointers; however, FXBREADM will reuse any pointers passed into the procedure, and hence any pointed-to data will be destroyed. FXBREADM can also read variable-length columns from FITS binary tables. Since such data is not of a fixed size, it is returned as a structure. The structure has the following elements: VARICOL: ;; Flag: variable length column (= 1) N_ELEMENTS: ;; Total number of elements returned TYPE: ;; IDL data type code (integer) N_ROWS: ;; Number of rows read from table (integer) INDICES: ;; Indices of each row's data (integer array) DATA: ;; Raw data elements (variable type array) In order to gain access to the Ith row's data, one should examine DATA(INDICES(I):INDICES(I+1)-1), which is similar in construct to the REVERSE_INDICES keyword of the HISTOGRAM function. CALLING SEQUENCE: FXBREADM, UNIT, COL, DATA1, [ DATA2, ... DATA48, ROW=, BUFFERSIZE = ] /NOIEEE, /NOSCALE, /VIRTUAL, NANVALUE=, PASS_METHOD = POINTERS=, ERRMSG = , WARNMSG = , STATUS = , /DEFAULT_FLOAT] INPUT PARAMETERS : UNIT = Logical unit number corresponding to the file containing the binary table. COL = An array of columns in the binary table to read data from, either as character strings containing column labels (TTYPE), or as numerical column indices starting from column one. Outputs : DATA1, DATA2...DATA48 = A named variable to accept the data values, one for each column. The columns are stored in order of the list in COL. If the read operation fails for a particular column, then the corresponding output Dn variable is not altered. See the STATUS keyword. Ignored if PASS_METHOD is 'POINTER'. OPTIONAL INPUT KEYWORDS: ROW = Either row number in the binary table to read data from, starting from row one, or a two element array containing a range of row numbers to read. If not passed, then the entire column is read in. /DEFAULT_FLOAT = If set, then scaling with TSCAL/TZERO is done with floating point rather than double precision. /NOIEEE = If set, then then IEEE floating point data will not be converted to the host floating point format (and this by definition implies NOSCALE). The user is responsible for their own floating point conversion. /NOSCALE = If set, then the output data will not be scaled using the optional TSCAL and TZERO keywords in the FITS header. Default is to scale. VIRTUAL = If set, and COL is passed as a name rather than a number, then if the program can't find a column with that name, it will then look for a keyword with that name in the header. Such a keyword would then act as a "virtual column", with the same value for every row. DIMENSIONS = FXBREADM ignores this keyword. It is here for compatibility only. NANVALUE= Value signalling data dropout. All points corresponding to IEEE NaN (not-a-number) are converted to this number. Ignored unless DATA is of type float, double-precision or complex. PASS_METHOD = A scalar string indicating method of passing data from FXBREADM. Either 'ARGUMENT' (indicating pass by positional argument), or 'POINTER' (indicating passing an array of pointers by the POINTERS keyword). Default: 'ARGUMENT' POINTERS = If PASS_METHOD is 'POINTER' then an array of IDL pointers is returned in this keyword, one for each requested column. Any pointers passed into FXBREADM will have their pointed-to data destroyed. Ultimately the user is responsible for deallocating pointers. BUFFERSIZE = Raw data are transferred from the file in chunks to conserve memory. This is the size in bytes of each chunk. If a value of zero is given, then all of the data are transferred in one pass. Default is 32768 (32 kB). OPTIONAL OUTPUT KEYWORDS: ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. In order to use this feature, ERRMSG must be defined first, e.g. ERRMSG = '' FXBREAD, ERRMSG=ERRMSG, ... IF ERRMSG NE '' THEN ... WARNMSG = Messages which are considered to be non-fatal "warnings" are returned in this output string. Note that if some but not all columns are unreadable, this is considered to be non-fatal. STATUS = An output array containing the status for each column read, 1 meaning success and 0 meaning failure. Calls : IEEE_TO_HOST, FXPAR(), WHERENAN() Common : Uses common block FXBINTABLE--see "fxbintable.pro" for more information. Restrictions: The binary table file must have been opened with FXBOPEN. The data must be consistent with the column definition in the binary table header. The row number must be consistent with the number of rows stored in the binary table header. Generaly speaking, FXBREADM will be faster than iterative calls to FXBREAD when (a) a large number of columns is to be read or (b) the size in bytes of each cell is small, so that the overhead of the FOR loop in FXBREAD becomes significant. SIDE EFFECTS: If there are no elements to read in (the number of elements is zero), then the program sets !ERR to -1, and DATA is unmodified. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : C. Markwardt, based in concept on FXBREAD version 12 from IDLASTRO, but with significant and major changes to accomodate the multiple row/column technique. Mostly the parameter checking and general data flow remain. C. Markwardt, updated to read variable length arrays, and to pass columns by handle or pointer. 20 Jun 2001 C. Markwardt, try to conserve memory when creating the arrays 13 Oct 2001 Handle case of GE 50 columns, C. Markwardt, 18 Apr 2002 Handle case where TSCAL/TZERO changes type of column, C. Markwardt, 23 Feb 2003 Fix bug in handling of FOUND and numeric columns, C. Markwardt 12 May 2003 Removed pre-V5.0 HANDLE options W. Landsman July 2004 Fix bug when HANDLE options were removed, July 2004 Handle special cases of TSCAL/TZERO which emulate unsigned integers, Oct 2003 Add DEFAULT_FLOAT keyword to select float values instead of double for TSCAL'ed, June 2004 Read 64bit integer columns, E. Hivon, Mar 2008 Add support for columns with TNULLn keywords, C. Markwardt, Apr 2010 Add support for files larger than 2 GB, C. Markwardt, 2012-04-17
(See $IDLUTILS_DIR/goddard/pro/fits_bintable/fxbreadm.pro)
FXBSTATE()
NAME: FXBSTATE() PURPOSE: Returns the state of a FITS binary table. Explanation : This procedure returns the state of a FITS binary table that was either opened for read with the command FXBOPEN, or for write with the command FXBCREATE. Use : Result = FXBSTATE(UNIT) Inputs : UNIT = Logical unit number returned by FXBOPEN routine. Must be a scalar integer. Opt. Inputs : None. Outputs : The result of the function is the state of the FITS binary table that UNIT points to. This can be one of three values: 0 = Closed 1 = Open for read 2 = Open for write Opt. Outputs: None. Keywords : None. Calls : FXBFINDLUN Common : Uses common block FXBINTABLE--see "fxbintable.pro" for more information. Restrictions: None. Side effects: If UNIT is an undefined variable, then 0 (closed) is returned. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : None. Written : William Thompson, GSFC, 1 July 1993. Modified : Version 1, William Thompson, GSFC, 1 July 1993. Version : Version 1, 1 July 1993. Converted to IDL V5.0 W. Landsman September 1997
(See $IDLUTILS_DIR/goddard/pro/fits_bintable/fxbstate.pro)
FXBTDIM()
NAME: FXBTDIM() Purpose : Parse TDIM-like kwywords. Explanation : Parses the value of a TDIM-like keyword (e.g. TDIMnnn, TDESC, etc.) to return the separate elements contained within. Use : Result = FXBTDIM( TDIM_KEYWORD ) Inputs : TDIM_KEYWORD = The value of a TDIM-like keyword. Must be a character string of the form "(value1,value2,...)". If the parentheses characters are missing, then the string is simply returned as is, without any further processing. Opt. Inputs : None. Outputs : The result of the function is a character string array containing the values contained within the keyword parameter. If a numerical result is desired, then simply call, e.g. Result = FIX( FXBTDIM( TDIM_KEYWORD )) Opt. Outputs: None. Keywords : None. Calls : GETTOK Common : None. Restrictions: The input parameter must have the proper format. The separate values must not contain the comma character. TDIM_KEYWORD must not be an array. Side effects: None. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : William Thompson, Jan. 1992. William Thompson, Jan. 1993, renamed to be compatible with DOS limitations. Written : William Thompson, GSFC, January 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version : Version 1, 12 April 1993. Converted to IDL V5.0 W. Landsman September 1997
(See $IDLUTILS_DIR/goddard/pro/fits_bintable/fxbtdim.pro)
FXBTFORM
NAME: FXBTFORM PURPOSE : Returns information about FITS binary table columns. EXPLANATION : Procedure to return information about the format of the various columns in a FITS binary table. Use : FXBTFORM,HEADER,TBCOL,IDLTYPE,FORMAT,NUMVAL,MAXVAL Inputs : HEADER = Fits binary table header. Opt. Inputs : None. Outputs : TBCOL = Array of starting column positions in bytes. IDLTYPE = IDL data types of columns. FORMAT = Character code defining the data types of the columns. NUMVAL = Number of elements of the data arrays in the columns. MAXVAL = Maximum number of elements for columns containing variable length arrays, or zero otherwise. Opt. Outputs: None. Keywords : ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. In order to use this feature, ERRMSG must be defined first, e.g. ERRMSG = '' FXBTFORM, ERRMSG=ERRMSG, ... IF ERRMSG NE '' THEN ... Calls : FXPAR Common : None. Restrictions: None. Side effects: None. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : W. Thompson, Feb. 1992, from TBINFO by D. Lindler. W. Thompson, Jan. 1993, renamed to be compatible with DOS limitations. Written : William Thompson, GSFC, February 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version 2, William Thompson, GSFC, 21 June 1994 Added ERRMSG keyword. Version 3, William Thompson, GSFC, 23 June 1994 Modified so that ERRMSG is not touched if not defined. Version 4, William Thompson, GSFC, 9 April 1997 Modified so that variable length arrays can be read, even if the maximum array size is not in the header. Version 5 Wayne Landsman, GSFC, August 1997 Recognize double complex array type if since IDL version 4.0 Version 6 Optimized FXPAR call, CM 1999 Nov 18 Version 7: Wayne Landsman, GSFC Feb 2006 Added support for 64bit integer K format Version: Version 8: Wayne Landsman GSFC Apr 2010 Remove use of obsolete !ERR variable
(See $IDLUTILS_DIR/goddard/pro/fits_bintable/fxbtform.pro)
FXBWRITE
NAME: FXBWRITE Purpose : Write a binary data array to a disk FITS binary table file. Explanation : Each call to FXBWRITE will write to the data file, which should already have been created and opened by FXBCREATE. One needs to call this routine for every column and every row in the binary table. FXBFINISH will then close the file. Use : FXBWRITE, UNIT, DATA, COL, ROW Inputs : UNIT = Logical unit number corresponding to the file containing the binary table. DATA = IDL data array to be written to the file. COL = Column in the binary table to place data in, starting from column one. ROW = Row in the binary table to place data in, starting from row one. Opt. Inputs : None. Outputs : None. Opt. Outputs: None. Keywords : BIT = Number of bits in bit mask arrays (type "X"). Only used if the column is of variable size. NANVALUE= Value signalling data dropout. All points corresponding to this value are set to be IEEE NaN (not-a-number). Ignored unless DATA is of type float, double-precision or complex. ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. In order to use this feature, ERRMSG must be defined first, e.g. ERRMSG = '' FXBWRITE, ERRMSG=ERRMSG, ... IF ERRMSG NE '' THEN ... Calls : HOST_TO_IEEE Common : Uses common block FXBINTABLE--see "fxbintable.pro" for more information. Restrictions: The binary table file must have been opened with FXBCREATE. The data must be consistent with the column definition in the binary table header. The row number must be consistent with the number of rows stored in the binary table header. Side effects: None. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : W. Thompson, Jan 1992, based on WRITEFITS by J. Woffard and W. Landsman. W. Thompson, Feb 1992, modified to support variable length arrays. W. Thompson, Feb 1992, removed all references to temporary files. Written : William Thompson, GSFC, January 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version 2, William Thompson, GSFC, 21 July 1993. Fixed bug with variable length arrays. Version 3, William Thompson, GSFC, 31 May 1994 Added ERRMSG keyword. Version 4, William Thompson, GSFC, 23 June 1994 Modified so that ERRMSG is not touched if not defined. Version 5, Wayne Landsman, GSFC, 12 Aug 1997 Recognize IDL double complex data type Version : Version 5, 12 August 1997 Converted to IDL V5.0 W. Landsman September 1997
(See $IDLUTILS_DIR/goddard/pro/fits_bintable/fxbwrite.pro)
FXBWRITM
NAME: FXBWRITM PURPOSE: Write multiple columns/rows to a disk FITS binary table file. EXPLANATION : A call to FXBWRITM will write multiple rows and multiple columns to a binary table in a single procedure call. Up to fifty columns may be read in a single pass. The file should have already been opened with FXBOPEN (with write access) or FXBCREATE. FXBWRITM optimizes writing multiple columns by first writing a large chunk of data to the FITS file all at once. FXBWRITM cannot write variable-length arrays; use FXBWRITE instead. The number of columns is limited to 50 if data are passed by positional argument. However, this limitation can be overcome by passing pointers to FXBWRITM. The user should set the PASS_METHOD keyword to 'POINTER' as appropriate, and an array of pointers to the data in the POINTERS keyword. The user is responsible for freeing the pointers. CALLING SEQUENCE: FXBWRITM, UNIT, COL, D0, D1, D2, ..., [ ROW= , PASS_METHOD, NANVALUE= POINTERS=, BUFFERSIZE= ] INPUT PARAMETERS: UNIT = Logical unit number corresponding to the file containing the binary table. D0,..D49= An IDL data array to be written to the file, one for each column. These parameters will be igonred if data is passed through the POINTERS keyword. COL = Column in the binary table to place data in. May be either a list of column numbers where the first column is one, or a string list of column names. OPTIONAL INPUT KEYWORDS: ROW = Either row number in the binary table to write data to, starting from row one, or a two element array containing a range of row numbers to write. If not passed, then the entire column is written. NANVALUE= Value signalling data dropout. All points corresponding to this value are set to be IEEE NaN (not-a-number). Ignored unless DATA is of type float, double-precision or complex. NOSCALE = If set, then TSCAL/TZERO values are ignored, and data is written exactly as supplied. PASS_METHOD = A scalar string indicating method of passing data to FXBWRITM. One of 'ARGUMENT' (indicating pass by positional argument), or'POINTER' (indicating passing an array of pointers by the POINTERS keyword). Default: 'ARGUMENT' POINTERS = If PASS_METHOD is 'POINTER' then the user must pass an array of IDL pointers to this keyword, one for each column. Ultimately the user is responsible for deallocating pointers. BUFFERSIZE = Data are transferred in chunks to conserve memory. This is the size in bytes of each chunk. If a value of zero is given, then all of the data are transferred in one pass. Default is 32768 (32 kB). OPTIONAL OUTPUT KEYWORDS: ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. In order to use this feature, ERRMSG must be defined first, e.g. ERRMSG = '' FXBWRITE, ERRMSG=ERRMSG, ... IF ERRMSG NE '' THEN ... WARNMSG = Messages which are considered to be non-fatal "warnings" are returned in this output string. STATUS = An output array containing the status for each read, 1 meaning success and 0 meaning failure. PROCEDURE CALLS: None. EXAMPLE: Write a binary table 'sample.fits' giving 43 X,Y positions and a 21 x 21 PSF at each position: (1) First, create sample values x = findgen(43) & y = findgen(43)+1 & psf = randomn(seed,21,21,43) (2) Create primary header, write it to disk, and make extension header fxhmake,header,/initialize,/extend,/date fxwrite,'sample.fits',header fxbhmake,header,43,'TESTEXT','Test binary table extension' (3) Fill extension header with desired column names fxbaddcol,1,header,x[0],'X' ;Use first element in each array fxbaddcol,2,header,y[0],'Y' ;to determine column properties fxbaddcol,3,header,psf[*,*,0],'PSF' (4) Write extension header to FITS file fxbcreate,unit,'sample.fits',header (5) Use FXBWRITM to write all data to the extension in a single call fxbwritm,unit,['X','Y','PSF'], x, y, psf fxbfinish,unit ;Close the file COMMON BLOCKS: Uses common block FXBINTABLE--see "fxbintable.pro" for more information. RESTRICTIONS: The binary table file must have been opened with FXBCREATE or FXBOPEN (with write access). The data must be consistent with the column definition in the binary table header. The row number must be consistent with the number of rows stored in the binary table header. A PASS_METHOD of POINTER does not use the EXECUTE() statement and can be used with the IDL Virtual Machine. However, the EXECUTE() statement is used when the PASS_METHOD is by arguments. CATEGORY: Data Handling, I/O, FITS, Generic. PREVIOUS HISTORY: C. Markwardt, based on FXBWRITE and FXBREADM (ver 1), Jan 1999 WRITTEN: Craig Markwardt, GSFC, January 1999. MODIFIED: Version 1, Craig Markwardt, GSFC 18 January 1999. Documented this routine, 18 January 1999. C. Markwardt, added ability to pass by handle or pointer. Some bug fixes, 20 July 2001 W. Landsman/B.Schulz Allow more than 50 arguments when using pointers W. Landsman Remove pre-V5.0 HANDLE options July 2004 W. Landsman Remove EXECUTE() call with POINTERS May 2005 C. Markwardt Allow the output table to have TSCAL/TZERO keyword values; if that is the case, then the passed values will be quantized to match those scale factors before being written. Sep 2007 E. Hivon: write 64bit integer and double precison columns, Mar 2008 C. Markwardt Allow unsigned integers, which have special TSCAL/TZERO values. Feb 2009 C. Markwardt Add support for files larger than 2 GB, 2012-04-17
(See $IDLUTILS_DIR/goddard/pro/fits_bintable/fxbwritm.pro)
FXFINDEND
NAME: FXFINDEND Purpose : Find the end of a FITS file. Explanation : This routine finds the end of the last logical record in a FITS file, which may be different from that of the physical end of the file. Each FITS header is read in and parsed, and the file pointer is moved to where the next FITS extension header would be if there is one, or to the end of the file if not. Use : FXFINDEND, UNIT [, EXTENSION] Inputs : UNIT = Logical unit number for the opened file. Opt. Inputs : None. Outputs : None. Opt. Outputs: EXTENSION = The extension number that a new extension would have if placed at the end of the file. Keywords : None. Calls : FXHREAD, FXPAR Common : None. Restrictions: The file must have been opened for block I/O. There must not be any FITS "special records" at the end of the file. Side effects: None. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : William Thompson, Feb. 1992. Written : William Thompson, GSFC, February 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version : Version 1, 12 April 1993. Converted to IDL V5.0 W. Landsman September 1997 Added EXTENSION parameter, CM 1999 Nov 18 Allow for possible 64bit integer number of bytes W. Landsman Nov 2007 make Ndata a long64 to deal with large files. E. Hivon Mar 2008
(See $IDLUTILS_DIR/goddard/pro/fits_bintable/fxfindend.pro)
FXHCLEAN
NAME: FXHCLEAN Purpose : Removes required keywords from FITS header. Explanation : Removes any keywords relevant to array structure from a FITS header, preparatory to recreating it with the proper values. Use : FXHCLEAN, HEADER Inputs : HEADER = FITS header to be cleaned. Opt. Inputs : None. Outputs : HEADER = The cleaned FITS header is returned in place of the input array. Opt. Outputs: None. Keywords : ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. In order to use this feature, ERRMSG must be defined first, e.g. ERRMSG = '' FXHCLEAN, ERRMSG=ERRMSG, ... IF ERRMSG NE '' THEN ... Calls : SXDELPAR, FXPAR Common : None. Restrictions: HEADER must be a string array containing a properly formatted FITS header. Side effects: Warning: when cleaning a binary table extension header, not all of the keywords pertaining to columns in the table may be removed. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : William Thompson, Jan 1992. Written : William Thompson, GSFC, January 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version 2, William Thompson, GSFC, 31 May 1994 Added ERRMSG keyword. Version 3, William Thompson, GSFC, 23 June 1994 Modified so that ERRMSG is not touched if not defined. Version 4, William Thompson, GSFC, 30 December 1994 Added TCUNIn to list of column keywords to be removed. Version : Version 4, 30 December 1994 Converted to IDL V5.0 W. Landsman September 1997
(See $IDLUTILS_DIR/goddard/pro/fits_bintable/fxhclean.pro)
FXHMAKE
NAME: FXHMAKE Purpose : Create a basic FITS header array. Explanation : Creates a basic header array with all the required keywords. This defines a basic structure which can then be added to or modified by other routines. Use : FXHMAKE, HEADER [, DATA ] Inputs : None required. Opt. Inputs : DATA = IDL data array to be written to file. It must be in the primary data unit unless the XTENSION keyword is supplied. This array is used to determine the values of the BITPIX and NAXIS, etc. keywords. If not passed, then BITPIX is set to eight, NAXIS is set to zero, and no NAXISnnn keywords are included in this preliminary header. Outputs : HEADER = String array containing FITS header. Opt. Outputs: None. Keywords : INITIALIZE = If set, then the header is completely initialized, and any previous entries are lost. EXTEND = If set, then the keyword EXTEND is inserted into the file, with the value of "T" (true). DATE = If set, then the DATE keyword is added to the header. ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. In order to use this feature, ERRMSG must be defined first, e.g. ERRMSG = '' FXHMAKE, ERRMSG=ERRMSG, ... IF ERRMSG NE '' THEN ... XTENSION - If set, then the header is appropriate for an image extension, rather than the primary data unit. Calls : GET_DATE, FXADDPAR, FXHCLEAN Common : None. Restrictions: Groups are not currently supported. Side effects: BITPIX, NAXIS, etc. are defined such that complex arrays are stored as floating point, with an extra first dimension of two elements (real and imaginary parts). Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : William Thompson, Jan 1992, from SXHMAKE by D. Lindler and M. Greason. Differences include: * Use of FITS standard (negative BITPIX) to signal floating point numbers instead of (SDAS/Geis) DATATYPE keyword. * Storage of complex numbers as pairs of real numbers. * Support for EXTEND keyword, and for cases where there is no primary data array. * Insertion of DATE record made optional. Only required FITS keywords are inserted automatically. Written : William Thompson, GSFC, January 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version 2, William Thompson, GSFC, 21 June 1994 Added ERRMSG keyword. Version 3, William Thompson, GSFC, 23 June 1994 Modified so that ERRMSG is not touched if not defined. Version 4, Wayne Landsman, GSFC, 12 August 1997 Recognize double complex data type Converted to IDL V5.0 W. Landsman September 1997 Version 6, William Thompson, GSFC, 22 September 2004 Recognize unsigned integer types. Version 6.1, C. Markwardt, GSFC, 19 Jun 2005 Add the XTENSION keyword, which writes an XTENSION keyword instead of SIMPLE. Version : Version 6.1, 19 June 2005
(See $IDLUTILS_DIR/goddard/pro/fits_bintable/fxhmake.pro)
FXHMODIFY
NAME: FXHMODIFY PURPOSE : Modify a FITS header in a file on disk. Explanation : Opens a FITS file, and adds or modifies a parameter in the FITS header. Can be used for either the main header, or for an extension header. The modification is performed directly on the disk file. Use : FXHMODIFY, FILENAME, NAME, VALUE, COMMENT Inputs : FILENAME = String containing the name of the file to be read. NAME = Name of parameter, scalar string 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 is equal to either "COMMENT" or "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. Opt. Inputs : COMMENT = String field. The '/' is added by this routine. Added starting in position 31. If not supplied, or set equal to '' (the null string), then any previous comment field in the header for that keyword is retained (when found). Outputs : None. Opt. Outputs: None. Keywords : EXTENSION = Either the number of the FITS extension, starting with the first extension after the primary data unit being one; or a character string containing the value of EXTNAME to search for. If not passed, then the primary FITS header is modified. 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. ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. In order to use this feature, ERRMSG must be defined first, e.g. ERRMSG = '' FXHMODIFY, ERRMSG=ERRMSG, ... IF ERRMSG NE '' THEN ... Calls : FXHREAD, FXPAR, FXADDPAR, BLKSHIFT Restrictions: This routine can not be used to modify any of the keywords that control the structure of the FITS file, e.g. BITPIX, NAXIS, PCOUNT, etc. Doing so could corrupt the readability of the FITS file. Example: Modify the name 'OBJECT' keyword in the primary FITS header of a FITS file 'spec98.ccd' to contain the value 'test domeflat' IDL> fxhmodify, 'spec98.ccd', 'OBJECT', 'test domeflat' Side effects: If adding a record to the FITS header would increase the number of 2880 byte records stored on disk, then the file is enlarged before modification, unless the NOGROW keyword is passed. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : None. Written : William Thompson, GSFC, 3 March 1994. Modified : Version 1, William Thompson, GSFC, 3 March 1994. Version 2, William Thompson, GSFC, 31 May 1994 Added ERRMSG keyword. Version 3, William Thompson, GSFC, 23 June 1994 Modified so that ERRMSG is not touched if not defined. Version 3.1 Wayne Landsman GSFC 17 March 2006 Fix problem in BLKSHIFT call if primary header extended Version 3.2 W. Landsman 14 November 204 Allow for need for 64bit number of bytes ; Version : Version 3.2, 14 Nov 2007
(See $IDLUTILS_DIR/goddard/pro/fits_bintable/fxhmodify.pro)
FXHREAD
NAME: FXHREAD Purpose : Reads a FITS header from an opened disk file. Explanation : Reads a FITS header from an opened disk file. Use : FXHREAD, UNIT, HEADER [, STATUS ] Inputs : UNIT = Logical unit number. Opt. Inputs : Outputs : HEADER = String array containing the FITS header. Opt. Outputs: STATUS = Condition code giving the status of the read. Normally, this is zero, but is set to !ERR if an error occurs, or if the first byte of the header is zero (ASCII null). Keywords : None. Calls : None. Common : None. Restrictions: The file must already be positioned at the start of the header. It must be a proper FITS file. Side effects: The file ends by being positioned at the end of the FITS header, unless an error occurs. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : W. Thompson, Feb 1992, from READFITS by J. Woffard and W. Landsman. W. Thompson, Aug 1992, added test for SIMPLE keyword. Written : William Thompson, GSFC, February 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version : Version 1, 12 April 1993. Converted to IDL V5.0 W. Landsman September 1997
(See $IDLUTILS_DIR/goddard/pro/fits_bintable/fxhread.pro)
FXMOVE
NAME: FXMOVE PURPOSE: Skip to a specified extension number or name in a FITS file CALLING SEQUENCE: STATUS=FXMOVE(UNIT, EXT, /Silent) STATUS=FXMOVE(UNIT, EXTNAME, /Silent, EXT_NO=, ERRMSG= ) INPUT PARAMETERS: UNIT = An open unit descriptor for a FITS data stream. EXTEN = Number of extensions to skip. or Scalar string giving extension name (in the EXTNAME keyword) OPTIONAL INPUT PARAMETER: /SILENT - If set, then any messages about invalid characters in the FITS file are suppressed. OPTIONAL OUTPUT PARAMETER: ERRMSG = If this keyword is present, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. RETURNS: 0 if successful. -1 if an error is encountered. COMMON BLOCKS: None. SIDE EFFECTS: Repositions the file pointer. PROCEDURE: Each FITS header is read in and parsed, and the file pointer is moved to where the next FITS extension header until the desired extension is reached. PROCEDURE CALLS: FXPAR(), MRD_HREAD, MRD_SKIP MODIFICATION HISTORY: Extracted from FXPOSIT 8-March-2000 by T. McGlynn Added /SILENT keyword 14-Dec-2000 by W. Landsman Save time by not reading the full header W. Landsman Feb. 2003 Allow extension name to be specified, added EXT_NO, ERRMSG keywords W. Landsman December 2006 Make search for EXTNAME case-independent W.Landsman March 2007 Avoid round-off error for very large extensions N. Piskunov Dec 2007 Assume since V6.1 (/INTEGER keyword available to PRODUCT() ) Dec 2007 Capture error message from MRD_HREAD (must be used with post-June 2009 version of MRD-HREAD) W. Landsman July 2009
(See $IDLUTILS_DIR/goddard/pro/fits/fxmove.pro)
FXPAR()
NAME: FXPAR() PURPOSE: Obtain the value of a parameter in a FITS header. EXPLANATION: The first 8 chacters of each element of HDR are searched for a match to NAME. If the keyword is one of those allowed to take multiple values ("HISTORY", "COMMENT", or " " (blank)), then the value is taken as the next 72 characters. Otherwise, it is assumed that the next character is "=", and the value (and optional comment) is then parsed from the last 71 characters. An error occurs if there is no parameter with the given name. If the value is too long for one line, it may be continued on to the the next input card, using the CONTINUE Long String Keyword convention. For more info, http://fits.gsfc.nasa.gov/registry/continue_keyword.html Complex numbers are recognized as two numbers separated by one or more space characters. If a numeric value has no decimal point (or E or D) 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. If an integer is too large to be stored as type LONG, then it is returned as DOUBLE. CALLING SEQUENCE: Result = FXPAR( HDR, NAME [, ABORT, COUNT=, COMMENT=, /NOCONTINUE ] ) Result = FXPAR(HEADER,'DATE') ;Finds the value of DATE Result = FXPAR(HEADER,'NAXIS*') ;Returns array dimensions as ;vector REQUIRED INPUTS: HDR = FITS header string array (e.g. as returned by FXREAD). 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, unless DATATYPE is given. OPTIONAL INPUT: ABORT = String specifying that FXPAR 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, FXPAR will return with a negative !err if a keyword is not found. DATATYPE = A scalar value, indicating the type of vector data. All keywords will be cast to this type. Default: based on first keyword. Example: DATATYPE=0.0D (cast data to double precision) START = A best-guess starting position of the sought-after keyword in the header. If specified, then FXPAR first searches for scalar keywords in the header in the index range bounded by START-PRECHECK and START+POSTCHECK. This can speed up keyword searches in large headers. If the keyword is not found, then FXPAR searches the entire header. If not specified then the entire header is searched. Searches of the form 'keyword*' also search the entire header and ignore START. Upon return START is changed to be the position of the newly found keyword. Thus the best way to search for a series of keywords is to search for them in the order they appear in the header like this: START = 0L P1 = FXPAR('P1', START=START) P2 = FXPAR('P2', START=START) PRECHECK = If START is specified, then PRECHECK is the number of keywords preceding START to be searched. Default: 5 POSTCHECK = If START is specified, then POSTCHECK is the number of keywords after START to be searched. Default: 20 OUTPUT: The returned value of the function is the value(s) associated with the requested keyword in the header array. If the parameter is complex, double precision, floating point, long or string, then the result is of that type. Apostrophes are stripped from strings. If the parameter is logical, 1 is returned for T, and 0 is returned for F. If NAME was of form 'keyword*' then a vector of values are returned. OPTIONAL INPUT KEYWORDS: /NOCONTINUE = If set, then continuation lines will not be read, even if present in the header OPTIONAL OUTPUT KEYWORD: COUNT = Optional keyword to return a value equal to the number of parameters found by FXPAR. COMMENTS= Array of comments associated with the returned values. PROCEDURE CALLS: GETTOK(), VALID_NUM SIDE EFFECTS: The system variable !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. However, if the keyword is "HISTORY", "COMMENT", or " " (blank), then multiple values are returned. 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. REVISION HISTORY: Version 1, William Thompson, GSFC, 12 April 1993. Adapted from SXPAR Version 2, William Thompson, GSFC, 14 October 1994 Modified to use VALID_NUM instead of STRNUMBER. Inserted additional call to VALID_NUM to trap cases where character strings did not contain quotation marks. Version 3, William Thompson, GSFC, 22 December 1994 Fixed bug with blank keywords, following suggestion by Wayne Landsman. Version 4, Mons Morrison, LMSAL, 9-Jan-98 Made non-trailing ' for string tag just be a warning (not a fatal error). It was needed because "sxaddpar" had an error which did not write tags properly for long strings (over 68 characters) Version 5, Wayne Landsman GSFC, 29 May 1998 Fixed potential problem with overflow of LONG values Version 6, Craig Markwardt, GSFC, 28 Jan 1998, Added CONTINUE parsing Version 7, Craig Markwardt, GSFC, 18 Nov 1999, Added START, PRE/POSTCHECK keywords for better performance Version 8, Craig Markwardt, GSFC, 08 Oct 2003, Added DATATYPE keyword to cast vector keywords type Version 9, Paul Hick, 22 Oct 2003, Corrected bug (NHEADER-1) Version 10, W. Landsman, GSFC 2 May 2012 Keywords of form "name_0" cound confuse vector extractions
(See $IDLUTILS_DIR/goddard/pro/fits_bintable/fxpar.pro)
FXPARPOS()
NAME: FXPARPOS() Purpose : Finds position to insert record into FITS header. Explanation : Finds the position to insert a record into a FITS header. Called from FXADDPAR. Use : Result = FXPARPOS(KEYWRD, IEND [, BEFORE=BEFORE ] [, AFTER=AFTER ]) Inputs : KEYWRD = Array of eight-character keywords in header. IEND = Position of END keyword. Opt. Inputs : None. Outputs : Result of function is position to insert record. Opt. Outputs: None. Keywords : 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. If neither BEFORE or AFTER keywords are passed, then IEND is returned. Calls : None. Common : None. Restrictions: KEYWRD and IEND must be consistent with the relevant FITS header. Side effects: None. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : William Thompson, Jan 1992. Written : William Thompson, GSFC, January 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version : Version 1, 12 April 1993. Converted to IDL V5.0 W. Landsman September 1997
(See $IDLUTILS_DIR/goddard/pro/fits_bintable/fxparpos.pro)
FXPOSIT
NAME: FXPOSIT PURPOSE: Return the unit number of a FITS file positioned at specified extension EXPLANATION: The FITS file will be ready to be read at the beginning of the specified extension. Either an extension number or extension name can be specified. Called by headfits.pro, mrdfits.pro Modified in March 2009 to set the /SWAP_IF_LITTLE_ENDIAN keyword when opening a file, and **may not be compatible with earlier versions** CALLING SEQUENCE: unit=FXPOSIT(FILE, EXT_NO_OR_NAME, /READONLY, COMPRESS=program, UNIXPIPE=, ERRMSG= , EXTNUM= , UNIT=, /SILENT /FPACK, /NO_FPACK INPUT PARAMETERS: FILE = FITS file name, scalar string. If an empty string is supplied then the user will be prompted for the file name. The user will also be prompted if a wild card is supplied, and more than one file matches the wildcard. EXT_NO_OR_NAME = Either the extension to be moved to (scalar nonnegative integer) or the name of the extension to read (scalar string) RETURNS: Unit number of file or -1 if an error is detected. OPTIONAL INPUT KEYWORD PARAMETER: COMPRESS - If this keyword is set and non-zero, then then treat the file as compressed. If 1 assume a gzipped file. and use IDLs internal decompression facility. For Unix compressed or bzip2 compressed files spawn off a process to decompress and use its output as the FITS stream. If the keyword is not 1, then use its value as a string giving the command needed for decompression. /FPACK - Signal that the file is compressed with the FPACK software. http://heasarc.gsfc.nasa.gov/fitsio/fpack/ ) By default, (FXPOSIT will assume that if the file name extension ends in .fz that it is fpack compressed.) The FPACK software must be installed on the system /NO_FPACK - The unit will only be used to read the FITS header. In that case FPACK compressed files need not be uncompressed. LUNIT - Integer giving the file unit number. Use this keyword if you want to override the default use of GET_LUN to obtain a unit number. /READONLY - If this keyword is set and non-zero, then OPENR rather than OPENU will be used to open the FITS file. Note that compressed files are always set to /READONLY /SILENT If set, then suppress any messages about invalid characters in the FITS file. OPTIONAL OUTPUT KEYWORDS: EXTNUM - Nonnegative integer give the extension number actually read Useful only if the extension was specified by name. ERRMSG = If this keyword is present, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. UNIXPIPE - If set to 1, then the FITS file was opened with a UNIX pipe rather than with the OPENR command. This is only required when reading a FPACK, bzip or Unix compressed file. Note that automatic byteswapping cannnot be set for a Unix pipe, since the SWAP_IF_LITTLE_ENDIAN keyword is only available for the OPEN command, and it is the responsibilty of the calling routine to perform the byteswapping. SIDE EFFECTS: Opens and returns a file unit. PROCEDURE: Open the appropriate file, or spawn a command and intercept the output. Call FXMOVE to get to the appropriate extension. PROCEDURE CALLS: FXMOVE() MODIFICATION HISTORY: Derived from William Thompson's FXFINDEND routine. Modified by T.McGlynn, 5-October-1994. Modified by T.McGlynn, 25-Feb-1995 to handle compressed files. Pipes cannot be accessed using FXHREAD so MRD_HREAD was written. W. Landsman 23-Apr-1997 Force the /bin/sh shell when uncompressing T. McGlynn 03-June-1999 Use /noshell option to get rid of processes left by spawn. Use findfile to retain ability to use wildcards W. Landsman 03-Aug-1999 Use EXPAND_TILDE under Unix to find file T. McGlynn 04-Apr-2000 Put reading code into FXMOVE, additional support for compression from D.Palmer. W. Landsman/D.Zarro 04-Jul-2000 Added test for !VERSION.OS EQ 'Win32' (WinNT) W. Landsman 12-Dec-2000 Added /SILENT keyword W. Landsman April 2002 Use FILE_SEARCH for V5.5 or later W. Landsman Feb 2004 Assume since V5.3 (OPENR,/COMPRESS available) W. Landsman,W. Thompson, 2-Mar-2004, Add support for BZIP2 W. Landsman Don't leave open file if an error occurs W. Landsman Sep 2004 Treat FTZ extension as gzip compressed W. Landsman Feb 2006 Removed leading spaces (prior to V5.5) W. Landsman Nov 2006 Allow specification of extension name Added EXTNUM, ERRMSG keywords W. Landsman/N.Piskunov Dec 2007 Added LUNIT keyword W. Landsman Mar 2009 OPEN with /SWAP_IF_LITTLE_ENDIAN Added UNIXPIPE output keyword N. Rich May 2009 Check if filename is an empty string W. Landsman May 2009 Support FPACK compressed files Added /FPACK, /HEADERONLY keywords W.Landsman July 2009 Deprecated /HEADERONLY add /NO_FPACK W.Landsman July 2011 Check for SIMPLE in first 8 chars Use gunzip to decompress Unix. Z file since compress utility often not installed anymore)
(See $IDLUTILS_DIR/goddard/pro/fits/fxposit.pro)
FXREAD
NAME: FXREAD Purpose : Read basic FITS files. Explanation : Read an image array from a disk FITS file. Optionally allows the user to read in only a subarray and/or every Nth pixel. Use : FXREAD, FILENAME, DATA [, HEADER [, I1, I2 [, J1, J2 ]] [, STEP]] Inputs : FILENAME = String containing the name of the file to be read. Opt. Inputs : I1,I2 = Data range to read in the first dimension. If passed, then HEADER must also be passed. If not passed, or set to -1,-1, then the entire range is read. J1,J2 = Data range to read in the second dimension. If passed, then HEADER and I1,J2 must also be passed. If not passed, or set to -1,-1, then the entire range is read. STEP = Step size to use in reading the data. If passed, then HEADER must also be passed. Default value is 1. Ignored if less than 1. Outputs : DATA = Data array to be read from the file. Opt. Outputs: HEADER = String array containing the header for the FITS file. Keywords : /COMPRESS - If this keyword is set and non-zero, then then treat the file as gzip compressed. By default FXREAD assumes the file is gzip compressed if it ends in ".gz" NANVALUE = Value signalling data dropout. All points corresponding to IEEE NaN (not-a-number) are set to this value. Ignored unless DATA is of type float or double-precision. EXTENSION = FITS extension. It can be a scalar integer, indicating the extension number (extension number 0 is the primary HDU). It can also be a scalar string, indicating the extension name (EXTNAME keyword). Default: 0 (primary HDU) PROMPT = If set, then the optional parameters are prompted for at the keyboard. AVERAGE = If set, then the array size is reduced by averaging pixels together rather than by subselecting pixels. Ignored unless STEP is nontrivial. Note: this is much slower. YSTEP = If passed, then STEP is the step size in the 1st dimension, and YSTEP is the step size in the 2nd dimension. Otherwise, STEP applies to both directions. NOSCALE = If set, then the output data will not be scaled using the optional BSCALE and BZERO keywords in the FITS header. Default is to scale, if and only if BSCALE and BZERO are present and nontrivial. NOUPDATE = If set, then the optional BSCALE and BZERO keywords in the optional HEADER array will not be changed. The default is to reset these keywords to BSCALE=1, BZERO=0. Ignored if NOSCALE is set. ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. In order to use this feature, ERRMSG must be defined first, e.g. ERRMSG = '' FXREAD, ERRMSG=ERRMSG, ... IF ERRMSG NE '' THEN ... NODATA = If set, then the array is not read in, but the primary header is read. Calls : GET_DATE, IEEE_TO_HOST, FXADDPAR, FXHREAD, FXPAR, WHERENAN Common : None. Restrictions: Groups are not supported. The optional parameters I1, I2, and STEP only work with one or two-dimensional arrays. J1 and J2 only work with two-dimensional arrays. Use of the AVERAGE keyword is not compatible with arrays with missing pixels. Side effects: If the keywords BSCALE and BZERO are present in the FITS header, and have non-trivial values, then the returned array DATA is formed by the equation DATA = BSCALE*original + BZERO However, this behavior can overridden by using the /NOSCALE keyword. If the data is scaled, then the optional HEADER array is changed so that BSCALE=1 and BZERO=0. This is so that these scaling parameters are not applied to the data a second time by another routine. Also, history records are added storing the original values of these constants. Note that only the returned array is modified--the header in the FITS file itself is untouched. If the /NOUPDATE keyword is set, however, then the BSCALE and BZERO keywords are not changed. It is then the user's responsibility to ensure that these parameters are not reapplied to the data. In particular, these keywords should not be present in any header when writing another FITS file, unless the user wants their values to be applied when the file is read back in. Otherwise, FITS readers will read in the wrong values for the data array. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : W. Thompson, May 1992, based in part on READFITS by W. Landsman, and STSUB by M. Greason and K. Venkatakrishna. W. Thompson, Jun 1992, added code to interpret BSCALE and BZERO records, and added NOSCALE and NOUPDATE keywords. W. Thompson, Aug 1992, changed to call FXHREAD, and to add history records for BZERO, BSCALE. Minimium IDL Version: V5.3 (uses COMPRESS keyword to OPEN) Written : William Thompson, GSFC, May 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version 2, William Thompson, GSFC, 17 November 1993. Corrected bug with AVERAGE keyword on non-IEEE compatible machines. Corrected bug with subsampling on VAX machines. Version 3, William Thompson, GSFC, 31 May 1994 Added ERRMSG keyword. Version 4, William Thompson, GSFC, 23 June 1994 Modified so that ERRMSG is not touched if not defined. Version 5, Zarro (SAC/GSFC), 14 Feb 1997 Added I/O error checking Version 6, 20-May-1998, David Schlegel/W. Thompson Allow a single pixel to be read in. Change the signal to read in the entire array to be -1 Version 7 C. Markwardt 22 Sep 2003 If the image is empty (NAXIS EQ 0), or NODATA is set, then return only the header. Version 8 W. Landsman 29 June 2004 Added COMPRESS keyword, check for .gz extension Version 9, William Thompson, 19-Aug-2004 Make sure COMPRESS is treated as a scalar Version 10, Craig Markwardt, 01 Mar 2004 Add EXTENSION keyword and ability to read different extensions than the primary one. Version 11, W. Landsamn September 2006 Assume since V5.5, remove VMS support Version 11.1, W. Landsamn November 2007 Allow for possibility number of bytes requires 64 bit integer Version 12, William Thompson, 18-Jun-2010, update BLANK value.
(See $IDLUTILS_DIR/goddard/pro/fits_bintable/fxread.pro)
FXWRITE
NAME: FXWRITE Purpose : Write a disk FITS file. Explanation : Creates or appends to a disk FITS file and writes a FITS header, and optionally an image data array. Use : FXWRITE, FILENAME, HEADER [, DATA ] Inputs : FILENAME = String containing the name of the file to be written. HEADER = String array containing the header for the FITS file. Opt. Inputs : DATA = IDL data array to be written to the file. If not passed, then it is assumed that extensions will be added to the file. Outputs : None. Opt. Outputs: None. Keywords : NANVALUE = Value signalling data dropout. All points corresponding to this value are set to be IEEE NaN (not-a-number). Ignored unless DATA is of type float, double-precision or complex. NOUPDATE = If set, then the optional BSCALE and BZERO keywords in the HEADER array will not be changed. The default is to reset these keywords to BSCALE=1, BZERO=0. APPEND = If set, then an existing file will be appended to. Appending to a non-existent file will create it. If a primary HDU already exists then it will be modified to have EXTEND = T. ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. In order to use this feature, ERRMSG must be defined first, e.g. ERRMSG = '' FXWRITE, ERRMSG=ERRMSG, ... IF ERRMSG NE '' THEN ... Calls : CHECK_FITS, GET_DATE, HOST_TO_IEEE, FXADDPAR, FXPAR Common : None. Restrictions: If DATA is passed, then HEADER must be consistent with it. If no data array is being written to the file, then HEADER must also be consistent with that. The routine FXHMAKE can be used to create a FITS header. If found, then the optional keywords BSCALE and BZERO in the HEADER array is changed so that BSCALE=1 and BZERO=0. This is so that these scaling parameters are not applied to the data a second time by another routine. Also, history records are added storing the original values of these constants. (Other values of BZERO are used for unsigned integers.) If the /NOUPDATE keyword is set, however, then the BSCALE and BZERO keywords are not changed. The user should then be aware that FITS readers will apply these numbers to the data, even if the data is already converted to floating point form. Groups are not supported. Side effects: HEADER may be modified. One way it may be modified is describe above under NOUPDATE. The first header card may also be modified to conform to the FITS standard if it does not already agree (i.e. use of either the SIMPLE or XTENSION keyword depending on whether the image is the primary HDU or not). Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : W. Thompson, Jan 1992, from WRITEFITS by J. Woffard and W. Landsman. Differences include: * Made DATA array optional, and HEADER array mandatory. * Changed order of HEADER and DATA parameters. * No attempt made to fix HEADER array. W. Thompson, May 1992, changed open statement to force 2880 byte fixed length records (VMS). The software here does not depend on this file configuration, but other FITS readers might. W. Thompson, Aug 1992, added code to reset BSCALE and BZERO records, and added the NOUPDATE keyword. Written : William Thompson, GSFC, January 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version 2, William Thompson, GSFC, 31 May 1994 Added ERRMSG keyword. Version 3, William Thompson, GSFC, 23 June 1994 Modified so that ERRMSG is not touched if not defined. Version 4, William Thompson, GSFC, 12 August 1999 Catch error if unable to open file. Version 4.1 Wayne Landsman, GSFC, 02 May 2000 Remove !ERR in call to CHECK_FITS, Use ARG_PRESENT() Version 5, William Thompson, GSFC, 22 September 2004 Recognize unsigned integer types Version 5.1 W. Landsman 14 November 204 Allow for need for 64bit number of bytes Version 6, Craig Markwardt, GSFC, 30 May 2005 Ability to append to existing files Version : Version 6, 30 May 2005
(See $IDLUTILS_DIR/goddard/pro/fits_bintable/fxwrite.pro)
F_FORMAT
NAME: F_FORMAT PURPOSE: Choose a nice floating format for displaying an array of REAL data. EXPLANATION: Called by TVLIST, IMLIST. CALLING SEQUENCE: fmt = F_FORMAT( minval, maxval, factor, [ length ] ) INPUTS: MINVAL - REAL scalar giving the minimum value of an array of numbers for which one desires a nice format. MAXVAL - REAL scalar giving maximum value in array of numbers OPTIONAL INPUT: LENGTH - length of the output F format (default = 5) must be an integer scalar > 2 OUTPUT: FMT - an F or I format string, e.g. 'F5.1' FACTOR - factor of 10 by which to multiply array of numbers to achieve a pretty display using format FMT. EXAMPLE: Find a nice format to print an array of numbers with a minimum of 5.2e-3 and a maximum of 4.2e-2. IDL> fmt = F_FORMAT( 5.2e-3, 4.2e-2, factor ) yields fmt = '(F5.2)' and factor = .01, i.e. the array can be displayed with a F5.2 format after multiplication by 100. REVISION HISTORY: Written W. Landsman December 1988 Deal with factors < 1. August 1991 Deal with factors < 1. *and* a large range October 1992 Now returns In format rather than Fn.0 February, 1994 Converted to IDL V5.0 W. Landsman September 1997
(See $IDLUTILS_DIR/goddard/pro/misc/f_format.pro)
GALAGE
NAME: GALAGE PURPOSE: Determine the age of a galaxy given its redshift and a formation redshift. CALLING SEQUENCE: age = galage(z, [zform, H0 =, k=, lambda0 =, Omega_m= , q0 =, /SILENT])' INPUTS: z - positive numeric vector or scalar of measured redshifts zform - redshift of galaxy formation (> z), numeric positive scalar To determine the age of the universe at a given redshift, set zform to a large number (e.g. ~1000). OPTIONAL KEYWORD INPUTS: H0 - Hubble constant in km/s/Mpc, positive scalar, default is 70 /SILENT - If set, then the adopted cosmological parameters are not displayed at the terminal. No more than two of the following four parameters should be specified. None of them need be specified -- the adopted defaults are given. k - curvature constant, normalized to the closure density. Default is 0, (indicating a flat universe) Omega_m - Matter density, normalized to the closure density, default is 0.3. Must be non-negative Lambda0 - Cosmological constant, normalized to the closure density, default is 0.7 q0 - Deceleration parameter, numeric scalar = -R*(R'')/(R')^2, default is -0.55 OUTPUTS: age - age of galaxy in years, will have the same number of elements as the input Z vector EXAMPLE: (1) Determine the age of a galaxy observed at z = 1.5 in a cosmology with Omega_matter = 0.3 and Lambda = 0.0. Assume the formation redshift was at z = 25, and use the default Hubble constant (=70 km/s/Mpc) IDL> print,galage(1.5,25,Omega_m=0.3, Lambda = 0) ===> 3.35 Gyr (2) Plot the age of a galaxy in Gyr out to a redshift of z = 5, assuming the default cosmology (omega_m=0.3, lambda=0.7), and zform = 100 IDL> z = findgen(50)/10. IDL> plot,z,galage(z,100)/1e9,xtit='z',ytit = 'Age (Gyr)' PROCEDURE: For a given formation time zform and a measured z, integrate dt/dz from zform to z. Analytic formula of dt/dz in Gardner, PASP 110:291-305, 1998 March (eq. 7) COMMENTS: (1) Integrates using the IDL Astronomy Library procedure QSIMP. (The intrinsic IDL QSIMP() function is not called because of its ridiculous restriction that only scalar arguments can be passed to the integrating function.) The function 'dtdz' is defined at the beginning of the routine (so it can compile first). (2) Should probably be fixed to use a different integrator from QSIMP when computing age from an "infinite" redshift of formation. But using a large value of zform seems to work adequately. (3) An alternative set of IDL procedures for computing cosmological parameters is available at http://cerebus.as.arizona.edu/~ioannis/research/red/ PROCEDURES CALLED: COSMO_PARAM, QSIMP HISTORY: STIS version by P. Plait (ACC) June 1999 IDL Astro Version W. Landsman (Raytheon ITSS) April 2000 Avoid integer overflow for more than 32767 redshifts July 2001
(See $IDLUTILS_DIR/goddard/pro/astro/galage.pro)
GAL_FLAT
NAME: GAL_FLAT PURPOSE: Transforms the image of a galaxy so that the galaxy appears face-on EXPLANATION: Either a nearest-neighbor approximations or a bilinear interpolation may be used. CALLING SEQUENCE: RESULT = GAL_FLAT( image, ang, inc, [, cen, /INTERP ] ) INPUTS: IMAGE - Image to be transformed ANG - Angle of major axis, counterclockwise from Y-axis, degrees For an image in standard orientation (North up, East left) this is the Position Angle INC - Angle of inclination of galaxy, degrees OPTIONAL INPUTS: CEN - Two element vector giving the X and Y position of galaxy center If not supplied, then the galaxy center is assumed to coincide with the image center INPUT KEYWORDS: INTERP - If present, and non-zero, then bilinear interpolation will be performed. Otherwise a nearest neighbor approximation is used. OUTPUTS: RESULT - the transformed image, same dimensions and type as IMAGE METHOD: A set of 4 equal spaced control points are corrected for inclination using the procedure POLYWARP. These control points are used by POLY_2D to correct the whole image. REVISION HISTORY: Written by R. S. Hill, SASC Technologies Inc., 4 December 1985 Code cleaned up a bit W. Landsman December 1992 Converted to IDL V5.0 W. Landsman September 1997
(See $IDLUTILS_DIR/goddard/pro/astro/gal_flat.pro)
GAL_UVW
NAME: GAL_UVW PURPOSE: Calculate the Galactic space velocity (U,V,W) of star EXPLANATION: Calculates the Galactic space velocity U, V, W of star given its (1) coordinates, (2) proper motion, (3) distance (or parallax), and (4) radial velocity. CALLING SEQUENCE: GAL_UVW, U, V, W, [/LSR, RA=, DEC=, PMRA= ,PMDEC=, VRAD= , DISTANCE= PLX= ] OUTPUT PARAMETERS: U - Velocity (km/s) positive toward the Galactic *anti*center V - Velocity (km/s) positive in the direction of Galactic rotation W - Velocity (km/s) positive toward the North Galactic Pole REQUIRED INPUT KEYWORDS: User must supply a position, proper motion,radial velocity and distance (or parallax). Either scalars or vectors can be supplied. (1) Position: RA - Right Ascension in *Degrees* Dec - Declination in *Degrees* (2) Proper Motion PMRA = Proper motion in RA in arc units (typically milli-arcseconds/yr) If given mu_alpha --proper motion in seconds of time/year - then this is equal to 15*mu_alpha*cos(dec) PMDEC = Proper motion in Declination (typically mas/yr) (3) Radial Velocity VRAD = radial velocity in km/s (4) Distance or Parallax DISTANCE - distance in parsecs or PLX - parallax with same distance units as proper motion measurements typically milliarcseconds (mas) OPTIONAL INPUT KEYWORD: /LSR - If this keyword is set, then the output velocities will be corrected for the solar motion (U,V,W)_Sun = (-8.5, 13.38, 6.49) (Coskunoglu et al. 2011 MNRAS) to the local standard of rest. Note that the value of the solar motion through the LSR remains poorly determined. EXAMPLE: (1) Compute the U,V,W coordinates for the halo star HD 6755. Use values from Hipparcos catalog, and correct to the LSR ra = ten(1,9,42.3)*15. & dec = ten(61,32,49.5) pmra = 628.42 & pmdec = 76.65 ;mas/yr dis = 139 & vrad = -321.4 gal_uvw,u,v,w,ra=ra,dec=dec,pmra=pmra,pmdec=pmdec,vrad=vrad,dis=dis,/lsr ===> u=141.2 v = -491.7 w = 93.9 ;km/s (2) Use the Hipparcos Input and Output Catalog IDL databases (see http://idlastro.gsfc.nasa.gov/ftp/zdbase/) to obtain space velocities for all stars within 10 pc with radial velocities > 10 km/s dbopen,'hipp_new,hic' ;Need Hipparcos output and input catalogs list = dbfind('plx>100,vrad>10') ;Plx > 100 mas, Vrad > 10 km/s dbext,list,'pmra,pmdec,vrad,ra,dec,plx',pmra,pmdec,vrad,ra,dec,plx ra = ra*15. ;Need right ascension in degrees GAL_UVW,u,v,w,ra=ra,dec=dec,pmra=pmra,pmdec=pmdec,vrad=vrad,plx = plx forprint,u,v,w ;Display results METHOD: Follows the general outline of Johnson & Soderblom (1987, AJ, 93,864) except that U is positive outward toward the Galactic *anti*center, and the J2000 transformation matrix to Galactic coordinates is taken from the introduction to the Hipparcos catalog. REVISION HISTORY: Written, W. Landsman December 2000 fix the bug occuring if the input arrays are longer than 32767 and update the Sun velocity Sergey Koposov June 2008 vectorization of the loop -- performance on large arrays is now 10 times higher Sergey Koposov December 2008 More recent value of solar motion WL/SK Jan 2011
(See $IDLUTILS_DIR/goddard/pro/astro/gal_uvw.pro)
GAUSSIAN
NAME: GAUSSIAN PURPOSE: Compute the 1-d Gaussian function and optionally the derivative EXPLANATION: Compute the 1-D Gaussian function and optionally the derivative at an array of points. CALLING SEQUENCE: y = gaussian( xi, parms,[ pderiv ]) INPUTS: xi = array, independent variable of Gaussian function. parms = parameters of Gaussian, 2, 3 or 4 element array: parms[0] = maximum value (factor) of Gaussian, parms[1] = mean value (center) of Gaussian, parms[2] = standard deviation (sigma) of Gaussian. (if parms has only 2 elements then sigma taken from previous call to gaussian(), which is stored in a common block). parms[3] = optional, constant offset added to Gaussian. OUTPUT: y - Function returns array of Gaussian evaluated at xi. Values will be floating pt. (even if xi is double) unless the /DOUBLE keyword is set. OPTIONAL INPUT: /DOUBLE - set this keyword to return double precision for both the function values and (optionally) the partial derivatives. OPTIONAL OUTPUT: pderiv = [N,3] or [N,4] output array of partial derivatives, computed only if parameter is present in call. pderiv[*,i] = partial derivative at all xi absisca values with respect to parms[i], i=0,1,2,[3]. EXAMPLE: Evaulate a Gaussian centered at x=0, with sigma=1, and a peak value of 10 at the points 0.5 and 1.5. Also compute the derivative IDL> f = gaussian( [0.5,1.5], [10,0,1], DERIV ) ==> f= [8.825,3.25]. DERIV will be a 2 x 3 array containing the numerical derivative at the two points with respect to the 3 parameters. COMMON BLOCKS: None HISTORY: Written, Frank Varosi NASA/GSFC 1992. Converted to IDL V5.0 W. Landsman September 1997 Use machar() for machine precision, added /DOUBLE keyword, add optional constant 4th parameter W. Landsman November 2001
(See $IDLUTILS_DIR/goddard/pro/math/gaussian.pro)
GCIRC
NAME: GCIRC PURPOSE: Computes rigorous great circle arc distances. EXPLANATION: Input position can either be either radians, sexigesimal RA, Dec or degrees. All computations are double precision. CALLING SEQUENCE: GCIRC, U, RA1, DC1, RA2, DC2, DIS INPUTS: U -- integer = 0,1, or 2: Describes units of inputs and output: 0: everything radians 1: RAx in decimal hours, DCx in decimal degrees, DIS in arc seconds 2: RAx and DCx in degrees, DIS in arc seconds RA1 -- Right ascension or longitude of point 1 DC1 -- Declination or latitude of point 1 RA2 -- Right ascension or longitude of point 2 DC2 -- Declination or latitude of point 2 OUTPUTS: DIS -- Angular distance on the sky between points 1 and 2 See U above for units; double precision PROCEDURE: "Haversine formula" see http://en.wikipedia.org/wiki/Great-circle_distance NOTES: (1) If RA1,DC1 are scalars, and RA2,DC2 are vectors, then DIS is a vector giving the distance of each element of RA2,DC2 to RA1,DC1. Similarly, if RA1,DC1 are vectors, and RA2, DC2 are scalars, then DIS is a vector giving the distance of each element of RA1, DC1 to RA2, DC2. If both RA1,DC1 and RA2,DC2 are vectors then DIS is a vector giving the distance of each element of RA1,DC1 to the corresponding element of RA2,DC2. If the input vectors are not the same length, then excess elements of the longer ones will be ignored. (2) The function SPHDIST provides an alternate method of computing a spherical distance. (3) The haversine formula can give rounding errors for antipodal points. PROCEDURE CALLS: None MODIFICATION HISTORY: Written in Fortran by R. Hill -- SASC Technologies -- January 3, 1986 Translated from FORTRAN to IDL, RSH, STX, 2/6/87 Vector arguments allowed W. Landsman April 1989 Prints result if last argument not given. RSH, RSTX, 3 Apr. 1998 Remove ISARRAY(), V5.1 version W. Landsman August 2000 Added option U=2 W. Landsman October 2006 Use double precision for U=0 as advertised R. McMahon/W.L. April 2007 Use havesine formula, which has less roundoff error in the milliarcsecond regime W.L. Mar 2009
(See $IDLUTILS_DIR/goddard/pro/astro/gcirc.pro)
GCNTRD
NAME: GCNTRD PURPOSE: Compute the stellar centroid by Gaussian fits to marginal X,Y, sums EXPLANATION: GCNTRD uses the DAOPHOT "FIND" centroid algorithm by fitting Gaussians to the marginal X,Y distributions. User can specify bad pixels (either by using the MAXGOOD keyword or setting them to NaN) to be ignored in the fit. Pixel values are weighted toward the center to avoid contamination by neighboring stars. CALLING SEQUENCE: GCNTRD, img, x, y, xcen, ycen, [ fwhm , /SILENT, /DEBUG, MAXGOOD = , /KEEPCENTER ] INPUTS: IMG - Two dimensional image array X,Y - Scalar or vector integers giving approximate stellar center OPTIONAL INPUT: FWHM - floating scalar; Centroid is computed using a box of half width equal to 1.5 sigma = 0.637* FWHM. GCNTRD will prompt for FWHM if not supplied OUTPUTS: XCEN - the computed X centroid position, same number of points as X YCEN - computed Y centroid position, same number of points as Y Values for XCEN and YCEN will not be computed if the computed centroid falls outside of the box, or if there are too many bad pixels, or if the best-fit Gaussian has a negative height. If the centroid cannot be computed, then a message is displayed (unless /SILENT is set) and XCEN and YCEN are set to -1. OPTIONAL OUTPUT KEYWORDS: MAXGOOD= Only pixels with values less than MAXGOOD are used to in Gaussian fits to determine the centroid. For non-integer data, one can also flag bad pixels using NaN values. /SILENT - Normally GCNTRD prints an error message if it is unable to compute the centroid. Set /SILENT to suppress this. /DEBUG - If this keyword is set, then GCNTRD will display the subarray it is using to compute the centroid. /KeepCenter By default, GCNTRD first convolves a small region around the supplied position with a lowered Gaussian filter, and then finds the maximum pixel in a box centered on the input X,Y coordinates, and then extracts a new box about this maximum pixel. Set the /KeepCenter keyword to skip the convolution and finding the maximum pixel, and instead use a box centered on the input X,Y coordinates. PROCEDURE: Unless /KEEPCENTER is set, a small area around the initial X,Y is convolved with a Gaussian kernel, and the maximum pixel is found. This pixel is used as the center of a square, within which the centroid is computed as the Gaussian least-squares fit to the marginal sums in the X and Y directions. EXAMPLE: Find the centroid of a star in an image im, with approximate center 631, 48. Assume that bad (saturated) pixels have a value of 4096 or or higher, and that the approximate FWHM is 3 pixels. IDL> GCNTRD, IM, 631, 48, XCEN, YCEN, 3, MAXGOOD = 4096 MODIFICATION HISTORY: Written June 2004, W. Landsman following algorithm used by P. Stetson in DAOPHOT2. Modified centroid computation (as in IRAF/DAOFIND) to allow shifts of more than 1 pixel from initial guess. March 2008 First perform Gaussian convolution prior to finding maximum pixel to smooth out noise W. Landsman Jan 2009
(See $IDLUTILS_DIR/goddard/pro/idlphot/gcntrd.pro)
GEO2ECI
NAME: GEO2ECI PURPOSE: Convert geographic spherical coordinates to Earth-centered inertial coords EXPLANATION: Converts from geographic spherical coordinates [latitude, longitude, altitude] to ECI (Earth-Centered Inertial) [X,Y,Z] rectangular coordinates. JD time is also needed. Geographic coordinates are in degrees/degrees/km Geographic coordinates assume the Earth is a perfect sphere, with radius equal to its equatorial radius. ECI coordinates are in km from Earth center. CALLING SEQUENCE: ECIcoord=geo2eci(gcoord,JDtime) INPUT: gcoord: geographic [latitude,longitude,altitude], or a an array [3,n] of n such coordinates JDtime: Julian Day time, double precision. Can be a 1-D array of n such times. KEYWORD INPUTS: None OUTPUT: a 3-element array of ECI [X,Y,Z] coordinates, or an array [3,n] of n such coordinates, double precision COMMON BLOCKS: None PROCEDURES USED: CT2LST - Convert Local Civil Time to Local Mean Sidereal Time EXAMPLES: IDL> ECIcoord=geo2eci([0,0,0], 2452343.38982663D) IDL> print,ECIcoord -3902.9606 5044.5548 0.0000000 (The above is the ECI coordinates of the intersection of the equator and Greenwich's meridian on 2002/03/09 21:21:21.021) MODIFICATION HISTORY: Written by Pascal Saint-Hilaire (shilaire@astro.phys.ethz.ch) on 2002/05/14
(See $IDLUTILS_DIR/goddard/pro/astro/geo2eci.pro)
GEO2GEODETIC
NAME: GEO2GEODETIC PURPOSE: Convert from geographic/planetographic to geodetic coordinates EXPLANATION: Converts from geographic (latitude, longitude, altitude) to geodetic (latitude, longitude, altitude). In geographic coordinates, the Earth is assumed a perfect sphere with a radius equal to its equatorial radius. The geodetic (or ellipsoidal) coordinate system takes into account the Earth's oblateness. Geographic and geodetic longitudes are identical. Geodetic latitude is the angle between local zenith and the equatorial plane. Geographic and geodetic altitudes are both the closest distance between the satellite and the ground. The PLANET keyword allows a similar transformation for the other planets (planetographic to planetodetic coordinates). The EQUATORIAL_RADIUS and POLAR_RADIUS keywords allow the transformation for any ellipsoid. Latitudes and longitudes are expressed in degrees, altitudes in km. REF: Stephen P. Keeler and Yves Nievergelt, "Computing geodetic coordinates", SIAM Rev. Vol. 40, No. 2, pp. 300-309, June 1998 Planetary constants from "Allen's Astrophysical Quantities", Fourth Ed., (2000) CALLING SEQUENCE: ecoord=geo2geodetic(gcoord,[ PLANET=,EQUATORIAL_RADIUS=, POLAR_RADIUS=]) INPUT: gcoord = a 3-element array of geographic [latitude,longitude,altitude], or an array [3,n] of n such coordinates. OPTIONAL KEYWORD INPUT: PLANET = keyword specifying planet (default is Earth). The planet may be specified either as an integer (1-9) or as one of the (case-independent) strings 'mercury','venus','earth','mars', 'jupiter','saturn','uranus','neptune', or 'pluto' EQUATORIAL_RADIUS : Self-explanatory. In km. If not set, PLANET's value is used. POLAR_RADIUS : Self-explanatory. In km. If not set, PLANET's value is used. OUTPUT: a 3-element array of geodetic/planetodetic [latitude,longitude,altitude], or an array [3,n] of n such coordinates, double precision. COMMON BLOCKS: None RESTRICTIONS: Whereas the conversion from geodetic to geographic coordinates is given by an exact, analytical formula, the conversion from geographic to geodetic isn't. Approximative iterations (as used here) exist, but tend to become less good with increasing eccentricity and altitude. The formula used in this routine should give correct results within six digits for all spatial locations, for an ellipsoid (planet) with an eccentricity similar to or less than Earth's. More accurate results can be obtained via calculus, needing a non-determined amount of iterations. In any case, IDL> PRINT,geodetic2geo(geo2geodetic(gcoord)) - gcoord is a pretty good way to evaluate the accuracy of geo2geodetic.pro. EXAMPLES: Locate the geographic North pole, altitude 0., in geodetic coordinates IDL> geo=[90.d0,0.d0,0.d0] IDL> geod=geo2geodetic(geo); convert to equivalent geodetic coordinates IDL> PRINT,geod 90.000000 0.0000000 21.385000 As above, but for the case of Mars IDL> geod=geo2geodetic(geo,PLANET='Mars') IDL> PRINT,geod 90.000000 0.0000000 18.235500 MODIFICATION HISTORY: Written by Pascal Saint-Hilaire (shilaire@astro.phys.ethz.ch), May 2002 Generalized for all solar system planets by Robert L. Marcialis (umpire@lpl.arizona.edu), May 2002 Modified 2002/05/18, PSH: added keywords EQUATORIAL_RADIUS and POLAR_RADIUS
(See $IDLUTILS_DIR/goddard/pro/astro/geo2geodetic.pro)
GEO2MAG()
NAME: GEO2MAG() PURPOSE: Convert from geographic to geomagnetic coordinates EXPLANATION: Converts from GEOGRAPHIC (latitude,longitude) to GEOMAGNETIC (latitude, longitude). (Altitude remains the same) Latitudes and longitudes are expressed in degrees. CALLING SEQUENCE: mcoord=geo2mag(gcoord) INPUT: gcoord = a 2-element array of geographic [latitude,longitude], or an array [2,n] of n such coordinates. KEYWORD INPUTS: None OUTPUT: a 2-element array of magnetic [latitude,longitude], or an array [2,n] of n such coordinates COMMON BLOCKS: None EXAMPLES: geographic coordinates of magnetic south pole IDL> mcoord=geo2mag([79.3,288.59]) IDL> print,mcoord 89.999992 -173.02325 MODIFICATION HISTORY: Written by Pascal Saint-Hilaire (Saint-Hilaire@astro.phys.ethz.ch), May 2002
(See $IDLUTILS_DIR/goddard/pro/astro/geo2mag.pro)
GEODETIC2GEO
NAME: GEODETIC2GEO PURPOSE: Convert from geodetic (or planetodetic) to geographic coordinates EXPLANATION: Converts from geodetic (latitude, longitude, altitude) to geographic (latitude, longitude, altitude). In geographic coordinates, the Earth is assumed a perfect sphere with a radius equal to its equatorial radius. The geodetic (or ellipsoidal) coordinate system takes into account the Earth's oblateness. Geographic and geodetic longitudes are identical. Geodetic latitude is the angle between local zenith and the equatorial plane. Geographic and geodetic altitudes are both the closest distance between the satellite and the ground. The PLANET keyword allows a similar transformation for the other planets (planetodetic to planetographic coordinates). The EQUATORIAL_RADIUS and POLAR_RADIUS keywords allow the transformation for any ellipsoid. Latitudes and longitudes are expressed in degrees, altitudes in km. REF: Stephen P. Keeler and Yves Nievergelt, "Computing geodetic coordinates", SIAM Rev. Vol. 40, No. 2, pp. 300-309, June 1998 Planetary constants from "Allen's Astrophysical Quantities", Fourth Ed., (2000) CALLING SEQUENCE: gcoord = geodetic2geo(ecoord, [ PLANET= ] ) INPUT: ecoord = a 3-element array of geodetic [latitude,longitude,altitude], or an array [3,n] of n such coordinates. OPTIONAL KEYWORD INPUT: PLANET = keyword specifying planet (default is Earth). The planet may be specified either as an integer (1-9) or as one of the (case-independent) strings 'mercury','venus','earth','mars', 'jupiter','saturn','uranus','neptune', or 'pluto' EQUATORIAL_RADIUS : Self-explanatory. In km. If not set, PLANET's value is used. Numeric scalar POLAR_RADIUS : Self-explanatory. In km. If not set, PLANET's value is used. Numeric scalar OUTPUT: a 3-element array of geographic [latitude,longitude,altitude], or an array [3,n] of n such coordinates, double precision The geographic and geodetic longitudes will be identical. COMMON BLOCKS: None EXAMPLES: IDL> geod=[90,0,0] ; North pole, altitude 0., in geodetic coordinates IDL> geo=geodetic2geo(geod) IDL> PRINT,geo 90.000000 0.0000000 -21.385000 As above, but the equivalent planetographic coordinates for Mars IDL> geod=geodetic2geo(geod,PLANET='Mars'); IDL> PRINT,geod 90.000000 0.0000000 -18.235500 MODIFICATION HISTORY: Written by Pascal Saint-Hilaire (shilaire@astro.phys.ethz.ch), May 2002 Generalized for all solar system planets by Robert L. Marcialis (umpire@lpl.arizona.edu), May 2002 Modified 2002/05/18, PSH: added keywords EQUATORIAL_RADIUS and POLAR_RADIUS
(See $IDLUTILS_DIR/goddard/pro/astro/geodetic2geo.pro)
GETDECOMPOSEDSTATE
Provides a device-independent way to get the color decomposition state of the current graphics device. :Categories: Graphics, Utilities :Returns: Returns a 1 if color decomposition is turned on and a 0 if indexed color is used. :Keywords: Depth: out, optional, type=integer The depth of the color display. Typically 8 for indexed color devices and 24 for true-color devices. :Examples: IDL> currentState = GetDecomposedState() :Author: FANNING SOFTWARE CONSULTING:: David W. Fanning 1645 Sheely Drive Fort Collins, CO 80526 USA Phone: 970-221-0438 E-mail: david@idlcoyote.com Coyote's Guide to IDL Programming: http://www.idlcoyote.com :History: Change History:: Written, 12 December 2010 as a better named wrapper for DECOMPOSEDCOLOR program. DWF. :Copyright: Copyright (c) 2010, Fanning Software Consulting, Inc.
(See $IDLUTILS_DIR/goddard/pro/coyote/getdecomposedstate.pro)
GETOPT
NAME: GETOPT PURPOSE: Convert a string supplied by the user into a valid scalar or vector EXPLANATION: Distinct elements in the string may be separated by either a comma or a space. The output scalar or vector can be specified to be either integer or floating point. A null string is converted to a zero. CALLING SEQUENCE: option = GETOPT( input, [ type, numopt, COUNT = ]) INPUTS: input - string that was input by user in response to a prompt Arithmetic operations can be included in the string (see examples) OPTIONAL INPUTS: type - Either an "I" (integer) or an "F" (floating point) specifying the datatype of the output vector. Default is floating point numopt - number of values expected by calling procedure If less than NUMOPT values are supplied the output vector will be padded with zeros. OUTPUTS: option - scalar or vector containing the numeric conversion of the fields in the string INPUT. If NUMOPT is not supplied, the number of elements in OPTION will equal the number of distinct fields in INPUT. OPTIONAL INPUT KEYWORD: Count - integer giving the number of values actually returned by GETOPT. If the input is invalid then COUNT is set to -1 NOTES: (1) If an input is invalid, Count is set to -1 and the result is set to 999. (2) GETOPT uses the execute function to interpret the user string. Therefore GETOPT itself cannot be called with the EXECUTE function. (3) GETOPT has a hard limit of 10 tokens in the input string. EXAMPLES: (1) a = getopt( '3.4,5*4 ', 'I' ) yields a = [ 3, 20] (2) a = getopt( '5/2.', 'F', 5) yields a = [2.5,0.,0.,0.,0.] (3) a = getopt( '2*3,5,6') yields a = [6.,5.,6.] REVISON HISTORY: written by B. Pfarr, STX, 5/6/87 change value of !ERR W. Landsman STX, 6/30/88 Converted to IDL V5.0 W. Landsman September 1997
(See $IDLUTILS_DIR/goddard/pro/misc/getopt.pro)
GETPRIMARYSCREENSIZE
:Description: Provides a way to get the screen size of the primary monitor, especially when there are several being used. :Categories: Graphics :Params: none :Keywords: exclude_taskbar: in, optional, boolean, default=0 Set this keyword to exclude the taskbar from the monitor size. This keyword is ignored on all but Windows machines. :Author: Dick Jackson, www.dick-jackson.com :History: Change History:: Written, 8 March 2011. DJ Modified to only use IDLsysMonitorInfo for IDL 6.3 and higher. 23 Feb 2012. DWF. :Copyright: Copyright (c) 2011, Fanning Software Consulting, Inc.
(See $IDLUTILS_DIR/goddard/pro/coyote/getprimaryscreensize.pro)
GETPRO
NAME: GETPRO PURPOSE: Search !PATH for a procedure, and copy into user's working directory EXPLANATION: Extract a procedure from an IDL Library or directory given in the !PATH system variable and place it in the current default directory (presumably to be edited by the user). CALLING SEQUENCE: GETPRO, [ proc_name ] ;Find PROC_NAME in !PATH and copy OPTIONAL INPUT: proc_name - Character string giving the name of the IDL procedure or function. Do not give an extension. If omitted, the program will prompt for PROC_NAME. OUTPUTS: None. SIDE EFFECTS: A file with the extension .pro and a name given by PROC_NAME will be created on the user's directory. PROCEDURE: The FILE_WHICH() function is used to locate the procedure in the IDL !PATH. When found, FILE_COPY is used to copy the procedure into the user's current default directory. If not found in !PATH, then the ROUTINE_INFO() function is used to determine if it is an intrinsic IDL procedure. EXAMPLE: Put a copy of the USER library procedure CURVEFIT on the current directory IDL> getpro, 'CURVEFIT' RESTRICTIONS: User will be unable to obain source code for a native IDL function or procedure, or for a FORTRAN or C routine added with CALL_EXTERNAL. User must have write privilege to the current directory PROCEDURE CALLS: ZPARCHECK REVISION HISTORY: Written W. Landsman, STX Corp. June 1990 Now use intrinsic EXPAND_PATH() command W. Landsman November 1994 Use ROUTINE_NAMES() to check for intrinsic procs W. Landsman July 95 Update for Windows/IDL W. Landsman September 95 Check if procedure is in current directory W. Landsman June 1997 Use ROUTINE_INFO instead of undocumented ROUTINE_NAMES W.L. October 1998 Use FILE_WHICH() to locate procedure W. Landsman May 2006 Assume since V5.5, remove VMS support W. Landsman Sep 2006 Assume since V6.0, use file_basename() W.Landsman Feb 2009 Test for .sav file, more robust test for write privilege W.L. Jul 2010
(See $IDLUTILS_DIR/goddard/pro/misc/getpro.pro)
GETPSF
NAME: GETPSF PURPOSE: To generate a point-spread function (PSF) from observed stars. EXPLANATION: The PSF is represented as a 2-dimensional Gaussian (integrated over each pixel) and a lookup table of residuals. The lookup table and Gaussian parameters are output in a FITS image file. The PSF FITS file created by GETPSF can be read with the procedure RDPSF. Adapted from the 1986 STSDAS version of DAOPHOT CALLING SEQUENCE: GETPSF, image, xc, yc, apmag, sky, [ronois, phpadu, gauss, psf, idpsf, psfrad, fitrad, psfname, /DEBUG ] INPUTS: IMAGE - input image array XC - input vector of x coordinates (from FIND), these should be IDL (first pixel is (0,0)) convention. YC - input vector of y coordinates (from FIND) APMAG - vector of magnitudes (from APER), used for initial estimate of gaussian intensity. If APMAG is multidimensional, (more than 1 aperture was used in APER) then the first aperture is used. SKY - vector of sky values (from APER) OPTIONAL INPUTS: The user will be prompted for the following parameters if not supplied. RONOIS - readout noise per pixel, (in electrons, or equivalent photons) PHPADU - photons per analog digital unit, used to scale the data numbers in IMAGE into photon units IDPSF - subscripts of the list of stars created by APER which will be used to define the PSF. Stars whose centroid does not fall within PSFRAD of the edge of the frame, or for which a Gaussian fit requires more than 25 iterations, will be ignored when creating the final PSF. PSFRAD - the scalar radius, in pixels, of the circular area within which the PSF will be defined. This should be slightly larger than the radius of the brightest star that one will be interested in. FITRAD - the scalar radius, in pixels of the circular area used in the least-square star fits. Stetson suggest that FITRAD should approximately equal to the FWHM, slightly less for crowded fields. (FITRAD must be smaller than PSFRAD.) PSFNAME- Name of the FITS file that will contain the table of residuals, and the best-fit Gaussian parameters. This file is subsequently required for use by NSTAR. OPTIONAL OUTPUTS: GAUSS - 5 element vector giving parameters of gaussian fit to the first PSF star GAUSS(0) - height of the gaussian (above sky) GAUSS(1) - the offset (in pixels) of the best fitting gaussian and the original X centroid GAUSS(2) - similiar offset from the Y centroid GAUSS(3) - Gaussian sigma in X GAUSS(4) - Gaussian sigma in Y PSF - 2-d array of PSF residuals after a Gaussian fit. PROCEDURE: GETPSF fits a Gaussian profile to the core of the first PSF star and generates a look-up table of the residuals of the actual image data from the Gaussian fit. If desired, it will then fit this PSF to another star (using PKFIT) to determine its precise centroid, scale the same Gaussian to the new star's core, and add the differences between the actual data and the scaled Gaussian to the table of residuals. (In other words, the Gaussian fit is performed only on the first star.) OPTIONAL KEYWORD INPUT: DEBUG - if this keyword is set and non-zero, then the result of each fitting iteration will be displayed. PROCEDURES CALLED DAOERF, MAKE_2D, MKHDR, RINTER(), PKFIT, STRNUMBER(), STRN(), WRITEFITS REVISON HISTORY: Adapted from the 1986 version of DAOPHOT in STSDAS IDL Version 2 W Landsman November 1988 Use DEBUG keyword instead of !DEBUG W. Landsman May 1996 Converted to IDL V5.0 W. Landsman September 1997
(See $IDLUTILS_DIR/goddard/pro/idlphot/getpsf.pro)
GETROT
NAME: GETROT PURPOSE: Return the rotation and plate scale of an image from its FITS header EXPLANATION: Derive the counterclockwise rotation angle, and the X and Y scale factors of an image, from a FITS image header. The input parameter may be either a FITS image header or an astrometry structure (as obtained by extast.pro) CALLING SEQUENCE: GETROT, Hdr, [ Rot, CDelt, /SILENT, DEBUG = ] or GETROT, Astr, Rot, CDelt, /SILENT, DEBUG = ] INPUT PARAMETERS: HDR - FITS Image header (string array). Program will extract the astrometry structure or ASTR - ASTROMETRY structure, of the type returned by EXTAST. See the documentation for EXTAST.PRO for details. OPTIONAL OUTPUT PARAMETERS: ROT - Scalar giving the counterclockwise rotation of NORTH in DEGREES from the +Y axis of the image. CDELT- 2 element vector giving the scale factors in DEGREES/PIXEL in the X and Y directions. CDELT[1] is always positive, whereas CDELT[0] is negative for a normal left-handed coordinate system, and positive for a right-handed system. If no output variables are supplied (or /DEBUG is set), then GETROT will display the rotation and plate scale at the terminal. OPTIONAL INPUT KEYWORD ALT - single character 'A' through 'Z' or ' ' specifying an alternate astrometry system present in the FITS header. See extast.pro for more information on the ALT keyword. Ignored if an astrometry structure rather than FITS header is supplied. DEBUG - if DEBUG is set, GETROT will print the rotation for both the X and Y axis when these values are unequal. If DEBUG is set to 2, then the output parameter ROT will contain both X and Y rotations. /SILENT - if set, then do not provide a warning about a right-handed coordinate system PROCEDURE: If the FITS header already contains CDELT (and CD or CROTA) keyword, (as suggested by the Calabretta & Greisen (2002, A&A, 395, 1077) FITS standard) then this is used for the scale factor. If the header contains CD keywords but no CDELT keywords (as in IRAF headers) then the scale factor is derived from the CD matrix. In case of skew (different rotations of the X and Y axes), the rotations are averaged together if they are less than 2 degrees. Otherwise, a warning is given and the X rotation is used. PROCEDURES USED: EXTAST, GSSS_EXTAST REVISION HISTORY: Written W. Landsman STX January 1987 Option to return both rotations added. J. D. Offenberg, STX, Aug 1991 Use new astrometry structure W. Landsman Mar 1994 Recognize a GSSS header W. Landsman June 1994 Correct rotation determination with unequal CDELT values WL October 1998 Consistent conversion between CROTA and CD matrix WL October 2000 Correct CDELT computations for rotations near 90 deg WL November 2002 Preserve sign in the CDELT output WL June 2003 Check if latitude/longitude reversed in CTYPE WL February 2004 Fix problem in latitude check M.Lombardi/W.Landsman Sep 2004 Added ALT keyword W. Landsman May 2005 Account for any rotation of the native system by examining the value of LONGPOLE H. Taylor/W. Landsman Account for case where X,Y rotations differ by 2*!pi WL. Aug 2011
(See $IDLUTILS_DIR/goddard/pro/astrom/getrot.pro)
GETTOK
NAME: GETTOK PURPOSE: Retrieve the first part of a (vector) string up to a specified character EXPLANATION: GET TOKen - Retrieve first part of string until the character char is encountered. CALLING SEQUENCE: token = gettok( st, char, [ /EXACT, /NOTRIM ] ) INPUT: char - character separating tokens, scalar string INPUT-OUTPUT: st - string to get token from (on output token is removed unless /NOTRIM is set), scalar or vector OUTPUT: token - extracted string value is returned, same dimensions as st OPTIONAL INPUT KEYWORD: /EXACT - The default behaviour of GETTOK is to remove any leading blanks and (if the token is a blank) convert tabs to blanks. Set the /EXACT keyword to skip these steps and leave the input string unchanged before searching for the character tokens. /NOTRIM - if set, then the input string is left unaltered EXAMPLE: If ST is ['abc=999','x=3.4234'] then gettok(ST,'=') would return ['abc','x'] and ST would be left as ['999','3.4234'] PROCEDURE CALLS: REPCHR() HISTORY version 1 by D. Lindler APR,86 Remove leading blanks W. Landsman (from JKF) Aug. 1991 V5.3 version, accept vector input W. Landsman February 2000 Slightly faster implementation W. Landsman February 2001 Added EXACT keyword W. Landsman March 2004 Assume since V5.4, Use COMPLEMENT keyword to WHERE W. Landsman Apr 2006 Added NOTRIM keyword W. L. March 2011
(See $IDLUTILS_DIR/goddard/pro/misc/gettok.pro)
GETWRD
NAME: GETWRD PURPOSE: Return the n'th word from a text string. CATEGORY: CALLING SEQUENCE: wrd = getwrd(txt, n, [m]) INPUTS: txt = text string to extract from. in The first element is used if txt is an array. n = word number to get (first = 0 = def). in m = optional last word number to get. in KEYWORD PARAMETERS: Keywords: LOCATION = l. Return word n string location. DELIMITER = d. Set word delimiter (def = space & tab). /LAST means n is offset from last word. So n=0 gives last word, n=-1 gives next to last, ... If n=-2 and m=0 then last 3 words are returned. /NOTRIM suppresses whitespace trimming on ends. NWORDS=n. Returns number of words in string. OUTPUTS: wrd = returned word or words. out COMMON BLOCKS: getwrd_com NOTES: Note: If a NULL string is given (txt="") then the last string given is used. This saves finding the words again. If m > n wrd will be a string of words from word n to word m. If no m is given wrd will be a single word. n<0 returns text starting at word abs(n) to string end If n is out of range then a null string is returned. See also nwrds. MODIFICATION HISTORY: Ray Sterner, 6 Jan, 1985. R. Sterner, Fall 1989 --- converted to SUN. R. Sterner, Jan 1990 --- added delimiter. R. Sterner, 18 Mar, 1990 --- added /LAST. R. Sterner, 31 Jan, 1991 --- added /NOTRIM. R. Sterner, 20 May, 1991 --- Added common and NULL string. R. Sterner, 13 Dec, 1992 --- Made tabs equivalent to spaces. R. Sterner, 4 Jan, 1993 --- Added NWORDS keyword. R. Sterner, 2001 Jan 15 --- Fixed to use first element if not a scalar. Johns Hopkins University Applied Physics Laboratory. Copyright (C) 1985, 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.
(See $IDLUTILS_DIR/goddard/pro/jhuapl/getwrd.pro)
GET_COORDS
NAME: GET_COORDS PURPOSE: Converts a string with angular coordinates to floating point values. EXPLANATION: Although called by ASTRO.PRO, this is a general purpose routine. The user may input as floating point or sexigesimal. If user inputs calling procedure's job to convert hours to degrees if needed. Since the input string is parsed character-by-character, ANY character that is not a digit, minus sign or decimal point may be used as a delimiter, i.e. acceptable examples of user input are: 1:03:55 -10:15:31 1 3 55.0 -10 15 31 1*3 55 -10abcd15efghij31 1.065278 hello -10.25861 CALLING SEQUENCE: GET_COORDS, Coords, [ PromptString, NumVals, INSTRING =, /QUIET ] OPTIONAL INPUT: PromptString - A string to inform the user what data are to be entered OPTIONAL KEYWORD INPUT: InString - a keyword that, if set, is assumed to already contain the input data string to be parsed. If this keyword is set, then the user is not prompted for any input. /Quiet - if set the program won't printout any error messages, but bad input is still flagged by Coords=[-999,-999]. OUTPUT: Coords - a 2 element floating array containing the coordinates. The vector [-999,-999] is returned if there has been an error. OPTIONAL OUTPUT: NumVals - the number of separate values entered by the user: 2 if the user entered the coordinates as floating point numbers, 6 if the user entered the coordinates as sexigesimal numbers. Some calling procedures might find this information useful (e.g., to to print some output in the same format as the user's input). REVISION HISTORY: Written by Joel Parker, 5 MAR 90 Included InString and Quiet keywords. Cleaned up some of the code and comments. JWmP, 16 Jun 94 ******************************************************************************* Converted to IDL V5.0 W. Landsman September 1997
(See $IDLUTILS_DIR/goddard/pro/astro/get_coords.pro)
GET_DATE
NAME: GET_DATE PURPOSE: Return the (current) UTC date in CCYY-MM-DD format for FITS headers EXPLANATION: This is the format required by the DATE and DATE-OBS keywords in a FITS header. CALLING SEQUENCE: GET_DATE, FITS_date, [ in_date, /OLD, /TIMETAG ] OPTIONAL INPUTS: in_date - string (scalar or vector) containing dates in IDL systime() format (e.g. 'Tue Sep 25 14:56:14 2001') OUTPUTS: FITS_date = A scalar character string giving the current date. Actual appearance of dte depends on which keywords are supplied. No Keywords supplied - dte is a 10 character string with the format CCYY-MM-DD where <CCYY> represents a calendar year, <MM> the ordinal number of a calendar month within the calendar year, and <DD> the ordinal number of a day within the calendar month. /TIMETAG set - dte is a 19 character string with the format CCYY-MM-DDThh:mm:ss where <hh> represents the hour in the day, <mm> the minutes, <ss> the seconds, and the literal 'T' the ISO 8601 time designator /OLD set - dte is an 8 character string in DD/MM/YY format INPUT KEYWORDS: /TIMETAG - Specify the time to the nearest second in the DATE format /OLD - Return the DATE format formerly (pre-1997) recommended for FITS Note that this format is now deprecated because it uses only a 2 digit representation of the year. EXAMPLE: Add the current date to the DATE keyword in a FITS header,h IDL> GET_DATE,dte IDL> sxaddpar, h, 'DATE', dte, 'Date header was created' NOTES: (1) A discussion of the DATExxx syntax in FITS headers can be found in http://www.cv.nrao.edu/fits/documents/standards/year2000.txt (2) Those who wish to use need further flexibility in their date formats (e.g. to use TAI time) should look at Bill Thompson's time routines in http://sohowww.nascom.nasa.gov/solarsoft/gen/idl/time PROCEDURES USED: DAYCNV - Convert Julian date to Gregorian calendar date REVISION HISTORY: Written W. Landsman March 1991 Major rewrite to write new DATExxx syntax W. Landsman August 1997 Converted to IDL V5.0 W. Landsman September 1997 Work after year 2000 even with /OLD keyword W. Landsman January 2000 Don't need to worry about TIME_DIFF since V5.4 W. Landsman July 2001 Assume since V5.4, remove LOCAL_DIFF keyword W. Landsman April 2006
(See $IDLUTILS_DIR/goddard/pro/astro/get_date.pro)
GET_EQUINOX
NAME: GET_EQUINOX PURPOSE: Return the equinox value from a FITS header. EXPLANATION: Checks for 4 possibilities: (1) If the EQUINOX keyword is found and has a numeric value, then this value is returned (2) If the EQUINOX keyword has the values 'J2000' or 'B1950', then either 2000. or 1950. is returned. (3) If the EQUINOX keyword is not found, then GET_EQUINOX will return the EPOCH keyword value. This usage of EPOCH is disparaged. (4) If neither EQUINOX no EPOCH is found, then the RADESYS keyword (or the deprecated RADECSYS keyword) is checked. If the value is 'ICRS' or 'FK5' then 2000 is is returned, if it is 'FK4' then 1950 is returned. According Calabretta & Greisen (2002, A&A, 395, 1077) the EQUINOX should be written as a numeric value, as in format (1). However, in older FITS headers, the EQUINOX might have been written using formats (2) or (3). CALLING SEQUENCE: Year = GET_EQUINOX( Hdr, [ Code ] ) INPUTS: Hdr - FITS Header, string array, will be searched for the EQUINOX (or EPOCH) keyword. OUTPUT: Year - Year of equinox in FITS header, numeric scalar OPTIONAL OUTPUT: Code - Result of header search, scalar -1 - EQUINOX, EPOCH or RADECSYS keyword not found in header 0 - EQUINOX found as a numeric value 1 - EPOCH keyword used for equinox (not recommended) 2 - EQUINOX found as 'B1950' 3 - EQUINOX found as 'J2000' 4 - EQUINOX derived from value of RADESYS or RADECSYS keyword 'ICRS', 'FK5' ==> 2000, 'FK4' ==> 1950 OPTIONAL KEYWORD INPUT: ALT - single character 'A' through 'Z' or ' ' specifying which astrometry system to use in the FITS header. The default is to use the primary astrometry or ALT = ''. If /ALT is set, then this is equivalent to ALT = 'A'. See Section 3.3 of Greisen & Calabretta (2002, A&A, 395, 1061) for information about alternate astrometry keywords. PROCEDURES USED: ZPARCHECK, SXPAR() NOTES: Technically, RADESYS = 'ICRS' does not specify any equinox, but can be assumed to be equivalent to J2000 for all but highest-precision work. REVISION HISTORY: Written W. Landsman STX March, 1991 Don't use !ERR W. Landsman February 2000 N = 1 for check of EPOCH keyword, not 0 S. Ott July 2000 Added ALT keyword, recognize RADESYS along with deprecated RADECSYS W. Landsman Sep 2011
(See $IDLUTILS_DIR/goddard/pro/astrom/get_equinox.pro)
GET_JULDATE
NAME: GET_JULDATE PURPOSE: Return the current Julian Date EXPLANATION: In V5.4, GET_JULDATE became completely obsolete with the introduction of the /UTC keyword to SYSTIME(). So GET_JULDATE,jd is equivalent to jd = SYSTIME(/JULIAN,/UTC). CALLING SEQUENCE: GET_JULDATE,jd INPUTS: None OUTPUTS: jd = Current Julian Date, double precision scalar EXAMPLE: Return the current hour, day, month and year as integers IDL> GET_JULDATE, JD ;Get current Julian date IDL> DAYCNV, JD, YR, MON, DAY, HOURS ;Convert to hour,day month & year METHOD: A call is made to SYSTIME(/JULIAN,/UTC). REVISION HISTORY: Written Wayne Landsman March, 1991 Converted to IDL V5.0 W. Landsman September 1997 Assume since V5.4 Use /UTC keyword to SYSTIME() W. Landsman April 2006
(See $IDLUTILS_DIR/goddard/pro/astro/get_juldate.pro)
GLACTC
NAME: GLACTC PURPOSE: Convert between celestial and Galactic (or Supergalactic) coordinates. EXPLANATION: Program to convert right ascension (ra) and declination (dec) to Galactic longitude (gl) and latitude (gb) (j=1) or vice versa (j=2). CALLING SEQUENCE: GLACTC, ra, dec, year, gl, gb, j, [ /DEGREE, /FK4, /SuperGalactic ] INPUT PARAMETERS: year equinox of ra and dec, scalar (input) j direction of conversion (input) 1: ra,dec --> gl,gb 2: gl,gb --> ra,dec INPUTS OR OUTPUT PARAMETERS: ( depending on argument J ) ra Right ascension, hours (or degrees if /DEGREES is set), scalar or vector dec Declination, degrees,scalar or vector gl Galactic longitude, degrees, scalar or vector gb Galactic latitude, degrees, scalar or vector All results forced double precision floating. OPTIONAL INPUT KEYWORD PARAMETERS: /DEGREE - If set, then the RA parameter (both input and output) is given in degrees rather than hours. /FK4 - If set, then the celestial (RA, Dec) coordinates are assumed to be input/output in the FK4 system. By default, coordinates are assumed to be in the FK5 system. For B1950 coordinates, set the /FK4 keyword *and* set the year to 1950. /SuperGalactic - If set, the GLACTC returns SuperGalactic coordinates as defined by deVaucouleurs et al. (1976) to account for the local supercluster. The North pole in SuperGalactic coordinates has Galactic coordinates l = 47.47, b = 6.32, and the origin is at Galactic coordinates l = 137.37, b= 0 EXAMPLES: Find the Galactic coordinates of Altair (RA (J2000): 19 50 47 Dec (J2000): 08 52 06) IDL> glactc, ten(19,50,47),ten(8,52,6),2000,gl,gb,1 ==> gl = 47.74, gb = -8.91 PROCEDURE CALLS: BPRECESS, JPRECESS, PRECESS HISTORY: FORTRAN subroutine by T. A. Nagy, 21-MAR-78. Conversion to IDL, R. S. Hill, STX, 19-OCT-87. Modified to handle vector input, E. P. Smith, GSFC, 14-OCT-94 Converted to IDL V5.0 W. Landsman September 1997 Added DEGREE keyword, C. Markwardt, Nov 1999 Major rewrite, default now FK5 coordinates, added /FK4 keyword use external precession routines W. Landsman April 2002 Add /Supergalactic keyword W. Landsman September 2002 Fix major bug when year not 2000 and /FK4 not set W. Landsman July 2003
(See $IDLUTILS_DIR/goddard/pro/astro/glactc.pro)
GLACTC_PM
NAME: GLACTC_PM PURPOSE: Convert between celestial and Galactic (or Supergalactic) proper motion (also converts coordinates). EXPLANATION: Program to convert proper motion in equatorial coordinates (ra,dec) to proper motion in Galactic coordinates (gl, gb) or Supergalacic Coordinates (sgl,sgb) or back to equatorial coordinates (j=2). The proper motion unit is arbitrary, but be sure to set /MUSTAR if units are the projection of the proper motion on the RA, Dec axis. It does precession on the coordinates but does not take care of precession of the proper motions which is usually a very small effect. CALLING SEQUENCE: GLACTC_PM, ra, dec, mu_ra,mu_dec,year, gl, gb, mu_gl, mu_gb, j, [ /DEGREE, /FK4, /SuperGalactic, /mustar ] INPUT PARAMETERS: year equinox of ra and dec, scalar (input) j direction of conversion (input) 1: ra,dec,mu_ra,mu_dec --> gl,gb,mu_gl,mu_gb 2: gl,gb,mu_gl,mu_gb --> ra,dec,mu_ra,mu_dec INPUTS OR OUTPUT PARAMETERS: ( depending on argument J ) ra Right ascension, hours (or degrees if /DEGREES is set), scalar or vector. dec Declination, degrees,scalar or vector mu_ra right ascension proper motion any proper motion unit (angle/time) mu_dec declination proper motion in any proper motion unit (angle/time) gl Galactic longitude, degrees, scalar or vector gb Galactic latitude, degrees, scalar or vector mu_gl galactic longitude proper motion in any time unit mu_gb galactic latitude proper motion in any time unit All results forced double precision floating. OPTIONAL INPUT KEYWORD PARAMETERS: /DEGREE - If set, then the RA parameter (both input and output) is given in degrees rather than hours. /FK4 - If set, then the celestial (RA, Dec) coordinates are assumed to be input/output in the FK4 system. By default, coordinates are assumed to be in the FK5 system. For B1950 coordinates, set the /FK4 keyword *and* set the year to 1950. /SuperGalactic - If set, the GLACTC returns SuperGalactic coordinates as defined by deVaucouleurs et al. (1976) to account for the local supercluster. The North pole in SuperGalactic coordinates has Galactic coordinates l = 47.47, b = 6.32, and the origin is at Galactic coordinates l = 137.37, b= 0 /mustar - if set then input and output of mu_ra and mu_dec are the projections of mu in the ra or dec direction rather than the d(ra)/dt or d(mu)/dt. So mu_ra becomes mu_ra*cos(dec) and mu_gl becomes mu_gl*cos(gb). EXAMPLES: Find the SuperGalactic proper motion of M33 given its equatorial proper motion mu* =(-29.3, 45.2) microas/yr. Where the (*) indicates ra component is actual mu_ra*cos(dec) (Position: RA (J2000): 01 33 50.9, Dec (J2000): 30 39 36.8) IDL> glactc_pm, ten(1,33,50.9),ten(30,39,36.8),-29.3,45.2, 2000,$ sgl,sgb,mu_sgl,mu_sgb,1,/Supergalactic,/mustar ==> SGL = 328.46732 deg, SGB = -0.089896901 deg, mu_sgl = 33.732 muas/yr, mu_gb = 41.996 muas/yr. And for the roundtrip: IDL> glactc_pm, ra,dec,mu_ra,mu_dec,2000,$ IDL> sgl,sgb,mu_sgl,mu_sgb,2,/Supergalactic,/mustar ==> ra=1.5641376 hrs., dec= 30.660277 deg, mu_ra= -29.300000 muas/yr, mu_dec=i 45.200000 muas/yr PROCEDURE CALLS: BPRECESS, JPRECESS, PRECESS HISTORY: Written Ed Shaya, U of MD, Oct 2009. Adapted from GLACTC to make proper motion transformations, Correct occasional sign error in galactic longitude E. Shaya Nov 2011
(See $IDLUTILS_DIR/goddard/pro/astro/glactc_pm.pro)
GROUP
NAME: GROUP PURPOSE: Assign stars with non-overlapping PSF profiles into distinct groups EXPLANATION: Part of the IDL-DAOPHOT sequence CALLING SEQUENCE: GROUP, X, Y, RCRIT, NGROUP INPUTS: X - vector, giving X coordinates of a set of stars. Y - vector, giving Y coordinates of a set of stars. If X and Y are input as integers, then they will be converted to floating point RCRIT - scalar, giving minimum distance between stars of two distinct groups. Stars less than this distance from each other are always in the same group. Stetson suggests setting the critical distance equal to the PSF radius + the Fitting radius. OUTPUTS: NGROUP - integer vector, same number of elements as X and Y, giving a group number for each star position. Group numbering begins with 0. METHOD: Each position is initially given a unique group number. The distance of each star is computed against every other star. Those distances less than RCRIT are assigned the minimum group number of the set. A check is then made to see if any groups have merged together. PROCEDURES USED: REM_DUP() REVISION HISTORY: Written W. Landsman STX April, 1988 Major revision to properly merge groups together W. Landsman Sep 1991 Work for more than 32767 points W. Landsman March 1997 Converted to IDL V5.0 W. Landsman September 1997 Avoid overflow if X and Y are integers W. Landsman Feb. 1999
(See $IDLUTILS_DIR/goddard/pro/idlphot/group.pro)
GSSSADXY
NAME: GSSSADXY PURPOSE: Converts RA and DEC (J2000) to (X,Y) for an STScI GuideStar image. EXPLANATION: The sky coordinates may be printed and/or returned in variables. CALLING SEQUENCE: GSSSADXY, GSA, Ra,Dec, [ X, Y, /Print ] INPUT: GSA - the GSSS Astrometry structure created by GSSSEXTAST RA - the RA coordinate(s) in *degrees*, scalar or vector DEC - the DEC coordinate(s) in *degrees*, scalar or vector OPTIONAL KEYWORD INPUT: /PRINT - If this keyword is set and non-zero, then coordinates will be displayed at the terminal OUTPUT: X - the corresponding X pixel coordinate(s), double precision Y - the corresponding Y pixel coordinate(s), double precision X and Y will be in IDL convention (first pixel 0,0) EXAMPLE: Given a FITS header, hdr, from the STScI Guidestar Survey, determine the X,Y coordinates of 3C 273 (RA = 12 29 6.7 +02 03 08) IDL> GSSSEXTAST, hdr, gsa ;Extract astrometry structure IDL> GSSSADXY, gsa, ten(12,29,6.7)*15,ten(2,3,8),/print NOTES: For most purpose users can simply use ADXY, which will call GSSSADXY if it is passed a GSSS header. PROCEDURES CALLED: ASTDISP - Print RA, Dec in standard format HISTORY: 10-JUL-90 Version 1 written by Eric W. Deutsch Derived from procedures written by Brian McLean Vectorized code W. Landsman March, 1991 14-AUG-91 Fixed error which caused returned X and Y to be .5 pixels too large. Now X,Y follows same protocol as ADXY. June 1994 - Dropped PRFLAG parameter, added /PRINT W. Landsman (HSTX) Converted to IDL V5.0 W. Landsman September 1997 29-JUN-99 Added support for AMD[X,Y]1[2-3] for DSS images by E. Deutsch Reduce memory requirements for large arrays D. Finkbeiner April 2004
(See $IDLUTILS_DIR/goddard/pro/astrom/gsssadxy.pro)
GSSSEXTAST
NAME: GSSSEXTAST PURPOSE: Extract IDL astrometry structure from a ST Guide Star Survey FITS header EXPLANATION: This procedure extracts the astrometry information from a ST Guide Star Survey FITS header and places it in an IDL structure for subsequent use with GSSSxyad and GSSSadxy. CALLING SEQUENCE: GSSSExtast, hdr, astr, noparams INPUT: h - the GSSS FITS header OUTPUT: astr - Structure containing the GSSS Astrometry information .CTYPE = ['RA---GSS','DEC--GSS'] .CRVAL = plate center Ra, Dec (from PLTRAH, PLTRAM etc.) .XLL,.YLL = offsets lower lefthand corner .AMDX, .AMDY = 12 transformation coefficients .XSZ,.YSZ = X and Y pixel size in microns .PLTSCL = plate scale in arc sec/mm .PPO3, .PPO6 - orientation coefficients NOTES: Most users should use EXTAST rather than this procedure. EXTAST will call GSSSEXTAST if supplied with GSSS FITS header. PROCEDURES CALLED: SXPAR() - Extract parameter values from a FITS header HISTORY: 01-JUL-90 Version 1 written by Eric W. Deutsch Code derived from Software by Brian McLean 20-AUG-91 Modified to Double Precision Variables. E. Deutsch June 94 Change astrometry tags to better agree with EXTAST W. Landsman Converted to IDL V5.0 W. Landsman September 1997 29-JUN-99 Added support for AMD[X,Y]1[2-3] for DSS images by E. Deutsch Eliminate use of obsolete !ERR W. Landsman February 2000
(See $IDLUTILS_DIR/goddard/pro/astrom/gsssextast.pro)
GSSSXYAD
NAME: GSSSXYAD PURPOSE: Convert (X,Y) coordinates in a STScI Guide Star image to RA and Dec EXPLANATION: The sky coordinates may be printed and/or returned in variables. CALLING SEQUENCE: GSSSxyad, gsa, x, y, ra, dec, [ /PRINT ] INPUT: GSA - The GSSS Astrometry structure extracted from a FITS header by GSSSEXTAST X - The X pixel coordinate(s) of the image, scalar or vector Y - The Y pixel coordinate(s) of the image, scalar or vector OUTPUT: RA - The RA coordinate of the given pixel(s) in *degrees* DEC - The DEC coordinate of the given pixel(s) in *degrees* Both RA and Dec will be returned as double precision OPTIONAL KEYWORD INPUT: /PRINT - If this keyword is set and non-zero, then coordinates will be displayed at the terminal EXAMPLE: Given a FITS header,hdr, from a GSSS image, print the astronomical coordinates of (X,Y) = (200.23, 100.16) at the terminal IDL> GSSSExtast, hdr, gsa ;Extract astrometry structure IDL> GSSSxyad, gsa, 200.23, 100.16, /print NOTES: For most purpose users can simply use XYAD, which will call GSSSXYAD if it is passed a GSSS header. PROCEDURES CALLED: ASTDISP - print RA, Dec in a standard format HISTORY: 01-JUL-90 Version 1 written by Eric W. Deutsch Vectorized Code W. Landsman March, 1991 14-AUG-91 Fixed error which caused returned RA and DEC to be off by -.5 pixels in both X,Y. Now X,Y follows same protocol as ADXY. 20-AUG-91 Modified to use AstDisp procedure. June 94 Added /PRINT keyword instead of PRFLAG W. Landsman June 94 Converted to IDL V5.0 W. Landsman September 1997 29-JUN-99 Added support for AMD[X,Y]1[2-3] for DSS images by E. Deutsch
(See $IDLUTILS_DIR/goddard/pro/astrom/gsssxyad.pro)
GSSS_STDAST
NAME: GSSS_STDAST PURPOSE: Insert the closest tangent projection astrometry into an GSSS Image DESCRIPTION: This procedure takes a header with GSSS (ST Guide Star Survey) astrometry and writes a roughly equivalent tangent projection astrometry into the header. One might want to do this if (1) one needs to use software which does not recognize the GSSS astrometric parameters or (2) if the the image to be transformed, since the highly nonlinear GSSS solution does not transform easily. CALLING SEQUENCE: GSSS_STDAST, H, [Xpts, Ypts] INPUT - OUTPUT: H - FITS header (string array) containing GSSS astrometry. GSSS_STDAST will write the roughly equivalent tangent projection astrometry solution into H. OPTIONAL INPUTS: xpts, ypts -- Vectors giving the X and Y positions of the three reference points used to find approximate tangent projection. Default is Xpts = [0.2,0.8,0.5], Ypts = [0.2, 0.4, 0.8] METHOD: The procedures GSSSXYAD is used to exactly determine the RA and Dec at 3 reference points. STARAST is then used to find the tangent projection astrometry that best matches these reference points. NOTES: Images from the STScI server (http://archive.stsci.edu/dss/) contain both a GSSS polynomial plate solution and an approximate WCS tangent projection. The value of the WCSNAME keyword in the FITS header is 'DSS'. If WCSNAME = "DSS' then the more accurate DSS astrometry is extracted by EXTAST This procedure changes the value of WCSNAME to 'DSS_TANGENT' to indicate that the tangent solution should be used. Some early GSSS images (before the 1994 CD-Rom) used keywords CRPIXx rather than CNPIXx. The GSSS astrometry in these images could be corrupted by this procedure as the CRPIXx values will be altered. The tangent is only a approximation of the nonlinear GSSS astrometry, but is generally accurate to about 0.1 pixels on a 1024 x 1024 image. PROCEDURES USED: GSSSEXTAST, GSSSXYAD, STARAST, PUTAST, SXADDHIST, SXDELPAR HISTORY: 13-AUG-91 Version 2 written from MAKEASTGSSS Eric Deutsch (STScI) Delete CDELT* keywords from header W. Landsman May 1994 Remove call to BUILDAST W. Landsman Jan, 1995 Added optional Xpts, Ypts parameters E. Deutsch Oct, 1995 Add WCSNAME W. Landsman Nov 2006
(See $IDLUTILS_DIR/goddard/pro/astrom/gsss_stdast.pro)
HADEC2ALTAZ
NAME: HADEC2ALTAZ PURPOSE: Converts Hour Angle and Declination to Horizon (alt-az) coordinates. EXPLANATION: Can deal with NCP/SCP singularity. Intended mainly to be used by program EQ2HOR CALLING SEQUENCE: HADEC2ALTAZ, ha, dec, lat ,alt ,az [ /WS ] INPUTS ha - the local apparent hour angle, in DEGREES, scalar or vector dec - the local apparent declination, in DEGREES, scalar or vector lat - the local latitude, in DEGREES, scalar or vector OUTPUTS alt - the local apparent altitude, in DEGREES. az - the local apparent azimuth, in DEGREES, all results in double precision OPTIONAL KEYWORD INPUT: /WS - Set this keyword for the output azimuth to be measured West from South. The default is to measure azimuth East from North. EXAMPLE: What were the apparent altitude and azimuth of the sun when it transited the local meridian at Pine Bluff Observatory (Lat=+43.07833 degrees) on April 21, 2002? An object transits the local meridian at 0 hour angle. Assume this will happen at roughly 1 PM local time (18:00 UTC). IDL> jdcnv, 2002, 4, 21, 18., jd ; get rough Julian date to determine ;Sun ra, dec. IDL> sunpos, jd, ra, dec IDL> hadec2altaz, 0., dec, 43.078333, alt, az ===> Altitude alt = 58.90 Azimuth az = 180.0 REVISION HISTORY: Written Chris O'Dell Univ. of Wisconsin-Madison May 2002
(See $IDLUTILS_DIR/goddard/pro/astro/hadec2altaz.pro)
HASIMAGEMAGICK
:Description: Searches for the ImageMagick "convert" command to see if ImageMagick is available on the system. :Categories: Utilities :Params: none. :Keywords: version: out, optional, type=string Returns the version number of the ImageMagick convert command, if found. :Examples: Used to determine if the ImageMagick convert command is available:: IDL> available = SearchForImageMagick(Version=version) IDL> IF available THEN Print, version :Author: FANNING SOFTWARE CONSULTING:: David W. Fanning 1645 Sheely Drive Fort Collins, CO 80526 USA Phone: 970-221-0438 E-mail: david@idlcoyote.com Coyote's Guide to IDL Programming: http://www.idlcoyote.com :History: Change History:: Written, 17 January 2011. DWF. :Copyright: Copyright (c) 2011, Fanning Software Consulting, Inc.
(See $IDLUTILS_DIR/goddard/pro/coyote/hasimagemagick.pro)
HASTROM
NAME: HASTROM PURPOSE: Transformation of an image to align it with a reference image EXPLANATION: A transformation is applied (using POLY_2D) to an image so that its astrometry is identical with that in a reference header. This procedure can be used to align two images. CALLING SEQUENCE: HASTROM, oldim, oldhd, newim, newhd, refhd, [MISSING =, INTERP = ] or HASTROM, oldim, oldhd, refhd, [MISSING =, INTERP ={0,1,2}, NGRID =, CUBIC =, DEGREE = ] INPUTS: OLDIM - Image array to be manipulated. If only 3 parameters are supplied then OLDIM and OLDHD will be modified to contain the output image array and header OLDHD - FITS header array for OLDIM, containing astrometry parameters REFHD - Reference header, containing astrometry parameters. OLDIM will be rotated, shifted, and compressed or expanded until its astrometry matches that in REFHD. OUTPUTS: NEWIM - Image array after transformation has been performed. The dimensions of NEWIM will be identical to the NAXIS1 and NAXIS2 keywords specified in REFHD. Regions on the reference image that do not exist in OLDIM can be assigned a value with the MISSING keyword. NEWHD - Updated FITS image header associated with NEWIM OPTIONAL INPUT KEYWORDS: MISSING - Set this keyword to a scalar value which will be assigned to pixels in the output image which are out of range of the supplied imput image. If not supplied, then linear extrapolation is used. See the IDL manual on POLY_2D. ***NOTE: A bug was introduced into the POLY_2D function in IDL V5.5 (fixed in V6.1) such that the MISSING keyword may not work properly with floating point data*** INTERP - Scalar, one of 0, 1, or 2 determining type of interpolation 0 nearest neighbor, 1 (default) bilinear interpolation, 2 cubic interpolation. CUBIC - a scalar value between -1 and 0 specifying cubic interpolation with the specified value as the cubic interpolation parameter. (see poly_2d for info). Setting CUBIC to a value greater than zero is equivalent to setting CUBIC = -1. NGRID - Integer scalar specifying the number of equally spaced grid points on each axis to use to specify the transformation. The value of NGRID must always be greater than DEGREE + 1. The default is DEGREE + 2 which equals 3 (9 total points) for DEGREE=1 (linear warping). DEGREE - Integer scalar specifying the degree of the transformation. See the routine POLYWARP for more info. Default = 1 (linear transformation) unless polynomial ('SIP') distortion parameters are present in either the input or reference FITS header. In that case, the default degree is equal to the degree of the distortion polynomial. OPTIONAL OUTPUT KEYWORD: ERRMSG - If this keyword is supplied, then any error messages will be returned to the user in this parameter rather than depending on on the MESSAGE routine in IDL. If no errors are encountered then a null string is returned. NOTES: (1) The 3 parameter calling sequence is less demanding on virtual memory. (2) The astrometry in OLDHD will be precessed to match the equinox given in REFHD. (3) If an ST Guidestar image is used for the reference header, then the output header will be converted to standard astrometry. EXAMPLE: Suppose one has an image array, IM, and an associated FITS header H. One desires to warp the image array so that it is aligned with another image with a FITS header, HREF. Both headers contain astrometry info. Set pixel values to 0 where there is no overlap between the input and reference image, and use linear interpolation (default) IDL> hastrom, IM, H, HREF, MISSING = 0 PROCEDURES USED: ad2xy, check_FITS, extast, get_EQUINOX(), gsssextast, hprecess, putast, sxaddpar, sxaddhist, sxpar(), xy2ad, zparcheck REVISION HISTORY: Written W. Landsman, STX Co. Feb, 1989 Updated to CHECK_FITS Dec, 1991 New astrometry keywords Mar, 1994 Recognize GSSS header W. Landsman June, 1994 Added CUBIC keyword W. Landsman March, 1997 Accept INTERP=0, Convert output GSS header to standard astrometry W. Landsman June 1998 Remove calls to obsolete !ERR system variable March 2000 Added ERRMSG output keyword W. Landsman April 2000 Need to re-extract astrometry after precession W. Landsman Nov. 2000 Check for distortion parameters in headers, add more FITS HISTORY information W. Landsman February 2005 Use different coefficient for nearest neighbor to avoid half-pixel shift with POLY_2D W. Landsman Aug 2006 Return ERRMSG if no overlap between images W. Landsman Nov 2007 Use V6.0 notation W. Landsman Jan 2012
(See $IDLUTILS_DIR/goddard/pro/astrom/hastrom.pro)
HBOXAVE
NAME: HBOXAVE PURPOSE: Box average an image array and update the FITS header array EXPLANATION: The function BOXAVE() is used. This procedure is recommended for integer images when photometric precision is desired, because it performs intermediate steps using REAL*4 arithmetic. Otherwise, the procedure HREBIN is much faster. CALLING SEQUENCE: HBOXAVE, Oldim, Oldhd, Newim, Hewhd, box or HBOXAVE, Oldim, Oldhd, box INPUTS: Oldim - the original image array Oldhd - the original image FITS header, string array OPTIONAL INPUTS: box - the box size to be used, integer scalar. If omitted, then HBOXAVE will prompt for this parameter. OPTIONAL OUTPUTS: Newim - the image after boxaveraging Newhd - header for newim containing updated astrometry info If output parameters are not supplied, the program will modify the input parameters OLDIM and OLDHD to contain the new array and updated header. OPTIONAL KEYWORD OUTPUT: ERRMSG - If this keyword is supplied, then any error mesasges will be returned to the user in this parameter rather than depending on on the MESSAGE routine in IDL. If no errors are encountered then a null string is returned. PROCEDURE: The parameters BSCALE, NAXIS1, NAXIS2, CRPIX1, and CRPIX2 and the CD (or CDELT) parameters are updated for the new FITS header. EXAMPLE: Compress the image in a FITS file 'image.fits' by a factor of 4 and update the astrometry in the FITS header IDL> im = readfits('image.fits',hdr) ;Read FITS file into IDL arrays IDL> hboxave, im, hdr, 4 ;Boxaverage by 4 IDL> writefits,'image.fits',im,hdr ;Write a new FITS file CALLED PROCEDURES: CHECK_FITS - Check that the FITS header is appropriate to the image BOXAVE() - Performs box averaging of an image SXPAR(), SXADDPAR - Read and write FITS keyword values MODIFICATION HISTORY: Written, Aug. 1986 W. Landsman, STI Corp. IDLV2 changes, sxaddpar format keyword added, J. Isensee, July,1990 Fix 0.5 pixel offset in new CRPIX computation W. Landsman, Dec, 1991 Update BSCALE even if no astrometry present W. Landsman, May 1997 Converted to IDL V5.0 W. Landsman September 1997 Added ERRMSG keyword, Use double formatting W. Landsman April 2000 Recognize PC matrix astrometry format W. Landsman December 2001
(See $IDLUTILS_DIR/goddard/pro/astrom/hboxave.pro)
HCONGRID
NAME: HCONGRID PURPOSE: CONGRID an image and update astrometry in a FITS header EXPLANATION: Expand or contract an image using CONGRID and update the associated FITS header array. CALLING SEQUENCE: HCONGRID, oldhd ;Update FITS header only HCONGRID, oldim, oldhd, [ newim, newhd, newx, newy, /HALF_HALF CUBIC = , INTERP=, OUTSIZE=, ERRMSG=, ALT= ] INPUTS: OLDIM - the original image array OLDHD - the original image FITS header, string array OPTIONAL INPUTS: NEWX - size of the new image in the X direction NEWY - size of the new image in the Y direction The OUTSIZE keyword can be used instead of the NEWX, NEWY parameters OPTIONAL OUTPUTS: NEWIM - the image after expansion or contraction with CONGRID NEWHD - header for newim containing updated astrometry info If output parameters are not supplied, the program will modify the input parameters OLDIM and OLDHD to contain the new array and updated header. OPTIONAL KEYWORD INPUTS: ALT - Single character 'A' through 'Z' or ' ' specifying which astrometry system to modify in the FITS header. The default is to use the primary astrometry of ALT = ' '. See Greisen and Calabretta (2002) for information about alternate astrometry keywords. CUBIC - If set and non-zero, then cubic interpolation is used. Valid ranges are -1 <= Cubic < 0. Setting /CUBIC is equivalent to CUBIC = -1 and also equivalent to INTERP = 2. See INTERPOLATE for more info. Setting CUBIC = -0.5 is recommended. ERRMSG - If this keyword is supplied, then any error mesasges will be returned to the user in this parameter rather than depending on on the MESSAGE routine in IDL. If no errors are encountered then a null string is returned. /HALF_HALF - Due to edge effects, the default behaviour of CONGRID is to introduce a slight shift in the image center. Craig Markwardt (http://cow.physics.wisc.edu/~craigm/idl/misc.html) has written a modified version of CONGRID called CMCONGRID that when used with the /HALF_HALF keyword eliminates any shift. The use of the /HALF keyword emulates CMCONGRID and eliminates any shift in the image centroid. INTERP - 0 for nearest neighbor, 1 for bilinear interpolation (default), 2 for cubic (=-1) interpolation. OUTSIZE - Two element integer vector which can be used instead of the NEWX and NEWY parameters to specify the output image dimensions OPTIONAL KEYWORD OUTPUT: ERRMSG - If this keyword is supplied, then any error mesasges will be returned to the user in this parameter rather than depending on on the MESSAGE routine in IDL. If no errors are encountered then a null string is returned. PROCEDURE: Expansion or contraction is done using the CONGRID function, unless HALF_HALF is set. The parameters BSCALE, NAXIS1, NAXIS2, CRPIX1, and CRPIX2 and the CD (or CDELT) parameters are updated for the new header. NOTES: A FITS header can be supplied as the first parameter without having to supply an image array. The astrometry in the FITS header will be updated to be appropriate to the specified image size. If the FITS header contains astrometry from a ST Guide Star image, then the astrometry will be converted to an approximately equivalent tangent projection before applying CONGRID. EXAMPLE: Congrid an 512 x 512 image array IM and FITS header H to size 300 x 300 using cubic interpolation. Use the HALF_HALF keyword to avoid a shift of the image centroid IDL> hcongrid, IM ,H, OUT = [300, 300], CUBIC = -0.5, /HALF The variables IM and H will be modified to the new image size. PROCEDURES CALLED: CHECK_FITS, CONGRID(), EXTAST, GSSS_STDAST, SXADDHIST, SXADDPAR, SXPAR(), ZPARCHECK MODIFICATION HISTORY: Written, Aug. 1986 W. Landsman, STI Corp. Added interp keywords, J. Isensee, July, 1990 Add cubic interpolation W. Landsman HSTX January 1994 Recognize a GSSS FITS header W. Landsman June 1994 Fix case where header but not image supplied W. Landsman May 1995 Remove call to SINCE_VERSION() W. Landsman March 1996 Assume since IDL V3.5, add CUBIC keyword W. Landsman March 1997 Update BSCALE even if no astrometry present W. Landsman May 1997 Converted to IDL V5.0 W. Landsman September 1997 Added HALF_HALF keyword W. Landsman February 2000 Added ERRMSG keyword, use double precision formatting W.L. April 2000 Recognize PC00n00m astrometry format W. Landsman December 2001 Now works when both /INTERP and /HALF are set W. Landsman January 2002 Fix output astrometry for non-equal plate scales for PC matrix or CROTA2 keyword, added ALT keyword. W. Landsman May 2005 Update distortion parameters if present W. Landsman January 2008 Don't update BSCALE/BZERO for unsigned integer W.Landsman Mar 2008
(See $IDLUTILS_DIR/goddard/pro/astrom/hcongrid.pro)
HEADFITS
NAME: HEADFITS PURPOSE: Read a FITS (primary or extension) header into a string array. EXPLANATION: HEADFITS() supports several types of compressed files including gzip (.gz), Unix compressed (.Z), Bzip2 (.bz2) or FPACK (.fz http://heasarc.gsfc.nasa.gov/fitsio/fpack/ ) CALLING SEQUENCE: Result = HEADFITS(Filename/Fileunit ,[ ERRMSG =, EXTEN= , COMPRESS=, /SILENT ]) INPUTS: Filename = String containing the name of the FITS file to be read. If set to an empty string, then user will be prompted for name. File names ending in '.gz' are assumed to be gzip'ed compressed and under Unix file names ending in '.Z' are assumed to be Unix compressed, and file names ending in .bz2 are assumed to be bzip2 compressed. If this default behaviour is not sufficient then use the COMPRESS keyword. or Fileunit - A scalar integer specifying the unit of an already opened FITS file. The unit will remain open after exiting HEADFITS(). There are two possible reasons for choosing to specify a unit number rather than a file name: (1) For a FITS file with many extensions, one can move to the desired extensions with FXPOSIT() and then use HEADFITS(). This is more efficient that repeatedly starting at the beginning of the file. (2) For reading a FITS file across a Web http: address after opening the unit with the SOCKET procedure. OPTIONAL INPUT KEYWORDS: EXTEN = Either an integer scalar, specifying which FITS extension to read, or a scalar string specifying the extension name (stored in the EXTNAME keyword). For example, to read the header of the first extension set EXTEN = 1. Default is to read the primary FITS header (EXTEN = 0). The EXTEN keyword cannot be used when a unit number is supplied instead of a file name. COMPRESS - If this keyword is set and non-zero, then treat the file as compressed. If 1 assume a gzipped file. Use IDL's internal decompression facilities for gzip files, while for Unix or bzip2 compression spawn off a process to decompress and use its output as the FITS stream. If the keyword is not 1, then use its value as a string giving the command needed for decompression. See FXPOSIT for more info. /SILENT - If set, then suppress any warning messages about invalid characters in the FITS file. OPTIONAL KEYWORD OUTPUT: ERRMSG = If this keyword is present, then any error messages will be returned to the user in this parameter rather than depending on the MESSAGE routine in IDL. If no errors are encountered, then a null string is returned. OUTPUTS: Result of function = FITS header, string array EXAMPLE: Print the main FITS header of a file 'test.fits' into a string variable, h IDL> print, headfits( 'test.fits') Print the second extension header of a gzip compressed FITS file 'test.fits.gz'. Use HPRINT for pretty format IDL> hprint, headfits( 'test.fits.gz', ext=2) Read the extension named CALSPEC IDL> hprint,headfits('test.fits.gz',ext='CALSPEC') PROCEDURES CALLED FXPOSIT(), MRD_HREAD The version of fxposit.pro must be post- May 2009. MODIFICATION HISTORY: adapted by Frank Varosi from READFITS by Jim Wofford, January, 24 1989 Keyword EXTEN added, K.Venkatakrishna, May 1992 Make sure first 8 characters are 'SIMPLE' W. Landsman October 1993 Check PCOUNT and GCOUNT W. Landsman December 1994 Major rewrite, work for Unix gzip files, W. Landsman April 1996 Added COMPRESS keyword W. Landsman April 2000 Added ERRMSG keyword W. Landsman July 2000 Added /SILENT keyword W. Landsman December 2000 Option to read a unit number rather than file name W.L October 2001 Test output status of MRD_HREAD call October 2003 W. Landsman Allow extension to be specified by name Dec 2006 W. Landsman No need to uncompress FPACK compressed files May 2009 W. Landsman Use V6.0 notation W.L. Feb. 2011
(See $IDLUTILS_DIR/goddard/pro/fits/headfits.pro)
HELIO
NAME: HELIO PURPOSE: Compute (low-precision) heliocentric coordinates for the planets. EXPLANATION: The mean orbital elements for epoch J2000 are used. These are derived from a 250 yr least squares fit of the DE 200 planetary ephemeris to a Keplerian orbit where each element is allowed to vary linearly with time. For dates between 1800 and 2050, this solution fits the terrestrial planet orbits to ~25" or better, but achieves only ~600" for Saturn. Use PLANET_COORDS (which calls HELIO) to get celestial (RA, Dec) coordinates of the planets CALLING SEQUENCE: HELIO, JD, LIST, HRAD, HLONG, HLAT, [/RADIAN] INPUTS: JD = Julian date, double precision scalar or vector LIST = List of planets array. May be a single number. 1 = merc, 2 = venus, ... 9 = pluto. OUTPUTS: HRAD = array of Heliocentric radii (A.U). HLONG = array of Heliocentric (ecliptic) longitudes (degrees). HLAT = array of Heliocentric latitudes (degrees). These output parameters will be dimensioned Nplanet by Ndate, where Nplanet is the number of elements of list, and Ndate is the number of elements of JD. OPTIONAL INPUT KEYWORD: /RADIAN - If set, then the output longitude and latitude are given in radians. EXAMPLE: (1) Find the current heliocentric positions of all the planets IDL> GET_JULDATE, jd ;Get current Julian date IDL> HELIO,jd,indgen(9)+1,hrad,hlong,hlat ;Get radius, long, and lat (2) Find heliocentric position of Mars on August 23, 2000 IDL> JDCNV, 2000,08,23,0,jd IDL> HELIO,JD,2,HRAD,HLONG,HLAT ===> hrad = 1.6407 AU hlong = 124.3197 hlat = 1.7853 For comparison, the JPL ephemeris gives hrad = 1.6407 AU hlong = 124.2985 hlat = 1.7845 (3) Find the heliocentric positions of Mars and Venus for every day in November 2000 IDL> JDCNV, 2000, 11, 1, 0, jd ;Julian date of November 1, 2000 IDL> helio, jd+indgen(30), [4,2], hrad,hlong,hlat ;Mars=4, Venus=2 hrad, hlong, and hlat will be dimensioned [2,30] first column contains Mars data, second column Venus COMMON BLOCKS: None ROUTINES USED: CIRRANGE - force angle between 0 and 2*!PI NOTES: (1) The calling sequence for this procedure was changed in August 2000 (2) This program is based on the two-body model and thus neglects interactions between the planets. This is why the worst results are for Saturn. Use the procedure JPLEPHINTERp for more accurate positions using the JPL ephemeris. Also see http://ssd.jpl.nasa.gov/cgi-bin/eph for a more accurate ephemeris generator online. (3) The coordinates are given for equinox 2000 and *not* the equinox of the supplied date(s) MODIFICATION HISTORY: R. Sterner. 20 Aug, 1986. Code cleaned up a bit W. Landsman December 1992 Major rewrite, use modern orbital elements, vectorize, more accurate solution to Kepler's equation W. Landsman August 2000 Wasn't working for planet vectors W. Landsman August 2000 Work for more than 32767 positions S. Leach Jan 2009
(See $IDLUTILS_DIR/goddard/pro/astro/helio.pro)
HELIO_JD
NAME: HELIO_JD PURPOSE: Convert geocentric (reduced) Julian date to heliocentric Julian date EXPLANATION: This procedure correct for the extra light travel time between the Earth and the Sun. An online calculator for this quantity is available at http://www.physics.sfasu.edu/astro/javascript/hjd.html Users requiring more precise calculations and documentation should look at the IDL code available at http://astroutils.astronomy.ohio-state.edu/time/ CALLING SEQUENCE: jdhelio = HELIO_JD( date, ra, dec, /B1950, /TIME_DIFF) INPUTS date - reduced Julian date (= JD - 2400000), scalar or vector, MUST be double precision ra,dec - scalars giving right ascension and declination in DEGREES Equinox is J2000 unless the /B1950 keyword is set OUTPUTS: jdhelio - heliocentric reduced Julian date. If /TIME_DIFF is set, then HELIO_JD() instead returns the time difference in seconds between the geocentric and heliocentric Julian date. OPTIONAL INPUT KEYWORDS /B1950 - if set, then input coordinates are assumed to be in equinox B1950 coordinates. /TIME_DIFF - if set, then HELIO_JD() returns the time difference (heliocentric JD - geocentric JD ) in seconds EXAMPLE: What is the heliocentric Julian date of an observation of V402 Cygni (J2000: RA = 20 9 7.8, Dec = 37 09 07) taken June 15, 1973 at 11:40 UT? IDL> juldate, [1973,6,15,11,40], jd ;Get geocentric Julian date IDL> hjd = helio_jd( jd, ten(20,9,7.8)*15., ten(37,9,7) ) ==> hjd = 41848.9881 Wayne Warren (Raytheon ITSS) has compared the results of HELIO_JD with the FORTRAN subroutines in the STARLINK SLALIB library (see http://star-www.rl.ac.uk/). Time Diff (sec) Date RA(2000) Dec(2000) STARLINK IDL 1999-10-29T00:00:00.0 21 08 25. -67 22 00. -59.0 -59.0 1999-10-29T00:00:00.0 02 56 33.4 +00 26 55. 474.1 474.1 1940-12-11T06:55:00.0 07 34 41.9 -00 30 42. 366.3 370.2 1992-02-29T03:15:56.2 12 56 27.4 +42 10 17. 350.8 350.9 2000-03-01T10:26:31.8 14 28 36.7 -20 42 11. 243.7 243.7 2100-02-26T09:18:24.2 08 26 51.7 +85 47 28. 104.0 108.8 PROCEDURES CALLED: bprecess, xyz, zparcheck REVISION HISTORY: Algorithm from the book Astronomical Photometry by Henden, p. 114 Written, W. Landsman STX June, 1989 Make J2000 default equinox, add B1950, /TIME_DIFF keywords, compute variation of the obliquity W. Landsman November 1999
(See $IDLUTILS_DIR/goddard/pro/astro/helio_jd.pro)
HELIO_RV
NAME: HELIO_RV PURPOSE: Return the heliocentric radial velocity of a spectroscopic binary EXPLANATION: This function will return the heliocentric radial velocity of a spectroscopic binary star at a given heliocentric date given its orbit. CALLING SEQUENCE: Result = HELIO_RV ( JD ,T ,Period ,Gamma , K, [,e ,Omega ] ) INPUT: JD - Time of observation T - Time of periastron passage (max. +ve velocity for circular orbits), same time system as JD Period - the period in same units as JD Gamma - systemic velocity K - velocity semi-amplitude in the same units as Gamma. e - eccentricity of the orbit, default is 0. Omega - longitude of periastron in degrees. Must be specified for eccentric orbits. OUTPUT: The predicted heliocentric radial velocity in the same units as Gamma for the date(s) specified by Reduced_HJD. RESTRICTIONS: The user should ensure consistency with all time systems being used (i.e. JD and T should be in the same units and time system). Generally, users should reduce large time values by subtracting a large constant offset, which may improve numerical accuracy. If using the the routines JULDATE and HELIO_JD, the reduced HJD time system must be used throughtout. EXAMPLES: Example 1 What was the heliocentric radial velocity of the primary component of HU Tau at 1730 UT 25 Oct 1994? IDL> juldate ,[94,10,25,17,30],JD ;Get Geocentric julian date IDL> hjd = helio_jd(jd,ten(04,38,16)*15.,ten(20,41,05)) ; Convert to HJD IDL> print, helio_rv(hjd,46487.5303D,2.0563056D,-6.0,59.3) -62.965569 NB. 1. The routines JULDATE and HELIO_JD return a reduced HJD (HJD - 2400000) and so T and P must be specified in the same fashion. 2. The user should be careful to use double precision format to specify T and P to sufficient precision where necessary. Example 2 Plot two cycles of an eccentric orbit, e=0.6, omega=45 for both components of a binary star IDL> phi=findgen(100)/50.0 ; Generates 100 phase points IDL> plot, phi,helio_rv(phi,0,1,0,100,0.6,45),yrange=[-100,150] IDL> oplot, phi,helio_rv(phi,0,1,0,50,0.6,45+180) This illustrates both the use of arrays to perform multiple calculations and generating radial velocities for a given phase by setting T=0 and P=1. Note also that omega has been changed by 180 degrees for the orbit of the second component (the same 'trick' can be used for circular orbits). MODIFICATION HISTORY: Written by: Pierre Maxted CUOBS, October, 1994 Circular orbits handled by setting e=0 and omega=0 to allow binary orbits to be handled using omega and omega+180. Pierre Maxted,Feb 95 BUG - omega was altered by the routine - corrected Feb 95,Pierre Maxted Iteration for E changed to that given by Reidel , Feb 95,Pierre Maxted /SINGLE keyword removed. May 96,Pierre Maxted ; Removed limitation of time system on HJD, C. Markwardt, 2011-04-15 Change convergence test from relative to absolute precision on E Pierre Maxted, Apr 12
(See $IDLUTILS_DIR/goddard/pro/astro/helio_rv.pro)
HERMITE
NAME: HERMITE PURPOSE: To compute Hermite spline interpolation of a tabulated function. EXPLANATION: Hermite interpolation computes the cubic polynomial that agrees with the tabulated function and its derivative at the two nearest tabulated points. It may be preferable to Lagrangian interpolation (QUADTERP) when either (1) the first derivatives are known, or (2) one desires continuity of the first derivative of the interpolated values. HERMITE() will numerically compute the necessary derivatives, if they are not supplied. CALLING SEQUENCE: F = HERMITE( XX, FF, X, [ FDERIV = ]) INPUT PARAMETERS: XX - Vector giving tabulated X values of function to be interpolated Must be either monotonic increasing or decreasing FF - Tabuluated values of function, same number of elements as X X - Scalar or vector giving the X values at which to interpolate OPTIONAL INPUT KEYWORD: FDERIV - function derivative values computed at XX. If not supplied, then HERMITE() will compute the derivatives numerically. The FDERIV keyword is useful either when (1) the derivative values are (somehow) known to better accuracy than can be computed numerically, or (2) when HERMITE() is called repeatedly with the same tabulated function, so that the derivatives need be computed only once. OUTPUT PARAMETER: F - Interpolated values of function, same number of points as X EXAMPLE: Interpolate the function 1/x at x = 0.45 using tabulated values with a spacing of 0.1 IDL> x = findgen(20)*0.1 + 0.1 IDL> y = 1/x IDL> print,hermite(x,y,0.45) This gives 2.2188 compared to the true value 1/0.45 = 2.2222 IDL> yprime = -1/x^2 ;But in this case we know the first derivatives IDL> print,hermite(x,y,0.45,fderiv = yprime) == 2.2219 ;and so can get a more accurate interpolation NOTES: The algorithm here is based on the FORTRAN code discussed by Hill, G. 1982, Publ Dom. Astrophys. Obs., 16, 67. The original FORTRAN source is U.S. Airforce. Surveys in Geophysics No 272. HERMITE() will return an error if one tries to interpolate any values outside of the range of the input table XX PROCEDURES CALLED: None REVISION HISTORY: Written, B. Dorman (GSFC) Oct 1993, revised April 1996 Added FDERIV keyword, W. Landsman (HSTX) April 1996 Test for out of range values W. Landsman (HSTX) May 1996 Converted to IDL V5.0 W. Landsman September 1997 Use VALUE_LOCATE instead of TABINV W. Landsman February 2001
(See $IDLUTILS_DIR/goddard/pro/math/hermite.pro)
HEULER
NAME: HEULER PURPOSE: Change the coordinate system of a FITS header or astrometry structure EXPLANATION: Converts a FITS header or a astrometry structure containing WCS (world coordinate system) information between celestial, ecliptic, and Galactic coordinates CALLING SEQUENCE: HEULER, hdr, [/GALACTIC, /CELESTIAL, /ECLIPTIC, ALT_IN = , ALT_OUT=] or HEULER, astr, /GALACTIC, /CELESTIAL, /ECLIPTIC INPUT/OUTPUT PARAMETERS: hdr - FITS header (string array) containing WCS information or Astr - Astrometry structure as extracted from a FITS header by extast.pro (See EXTAST for more info). Header or astrometry structure will be modified by the program to contain astrometry in the new coordinates system. REQUIRED INPUT KEYWORDS: One of the following exclusive keywords is *required* /GALACTIC - Convert the header to Galactic coordinates /CELESTIAL - Convert the header to celestial (RA & Dec) coordinates /ECLIPTIC - Convert the header to ecliptic coordinates OPTIONAL INPUT KEYWORDS: The following two keywords apply if the FITS header contains multiple WCS keywords. See Section 3.3 of Greisen & Calabretta (2002, A&A, 395, 1061) for information about alternate astrometry keywords. ALT_IN - single character 'A' through 'Z' or ' ' specifying an alternate astrometry system present in the input FITS header. The default isto use the primary astrometry or ALT = ' '. If /ALT_IN is set, then this is equivalent to ALT_IN = 'A'. ALT_OUT - single character specifying the alternate WCS keywords to write the *output* astrometry. If not specified, then ALT_OUT is set equal to ALT_IN. RESTRICTIONS: Currently assumes that celestial and ecliptic coordinates are in J2000. Use HPRECESS if this is not the case. ST Guide Star (DSS) image headers are first converted to a standard tangent projection, prior to the coordinate conversion METHOD: The algorithm used is described in Section 2.7 of Calabretta & Greisen (2002, A&A, 395, 1077). The CRVAL coordinates are transformed directly using EULER. The new LONPOLE and LATPOLE values are then determined by transforming the pole of the new system to the old, and converted to native coordinates using WCS_ROTATE. EXAMPLE: A FITS header, hdr, has a standard tangent projection WCS information. Add an alternate 'G' Galactic projection. Note that the original WCS information will be left unchanged IDL> heuler, hdr, /Galactic, alt='G' PROCEDURES USED: EULER, EXTAST, GSSS_STDAST, PUTAST, SXADDHIST, WCS_ROTATE REVISION HISTORY: Written W. Landsman June 2003 Use PV2 tag in astrometry structure rather than PROJP1 W. L. May 2004 Use double precision to compute new North pole W.L. Aug 2005
(See $IDLUTILS_DIR/goddard/pro/astrom/heuler.pro)
HEXTRACT
NAME: HEXTRACT PURPOSE: Extract a subimage from an array and update astrometry in FITS header EXPLANATION: Extract a subimage from an array and create a new FITS header with updated astrometry for the subarray CALLING SEQUENCE: HEXTRACT, Oldim, Oldhd, [ Newim, Newhd, x0, x1, y0, y1, /SILENT ] or HEXTRACT, Oldim, Oldhd, [x0, x1, y0, y1, /SILENT, ERRMSG = ] INPUTS: Oldim - the original image array Oldhd - the original image header OPTIONAL INPUTS: x0, x1, y0, y1 - respectively, first and last X pixel, and first and last Y pixel to be extracted from the original image, integer scalars. HEXTRACT will convert these values to long integers. If omitted, HEXTRACT will prompt for these parameters OPTIONAL OUTPUTS: Newim - the new subarray extracted from the original image Newhd - header for newim containing updated astrometry info If output parameters are not supplied or set equal to -1, then the HEXTRACT will modify the input parameters OLDIM and OLDHD to contain the subarray and updated header. OPTIONAL INPUT KEYWORD: ALT - Single character 'A' through 'Z' or ' ' specifying which astrometry system to modify in the FITS header. The default is to use the primary astrometry or ALT = ' '. See Greisen and Calabretta (2002) for information about alternate astrometry keywords. /SILENT - If set and non-zero, then a message describing the extraction is not printed at the terminal. This message can also be suppressed by setting !QUIET. OPTIONAL KEYWORD OUTPUT: ERRMSG - If this keyword is supplied, then any error mesasges will be returned to the user in this parameter rather than depending on on the MESSAGE routine in IDL. If no errors are encountered then a null string is returned. PROCEDURE: The FITS header parameters NAXIS1, NAXIS2, CRPIX1, and CRPIX2 are updated for the extracted image. EXAMPLE: Read an image from a FITS file 'IMAGE', extract a 512 x 512 subimage with the same origin, and write to a new FITS file 'IMAGENEW' IDL> im = READFITS( 'IMAGE', hdr ) ;Read FITS files into IDL arrays IDL> hextract, im, h, 0, 511, 0, 511 ;Extract 512 x 512 subimage IDL> writefits, 'IMAGENEW', im ,h ;Write subimage to a FITS file PROCEDURES CALLED CHECK_FITS, STRN(), SXPAR(), SXADDPAR, SXADDHIST MODIFICATION HISTORY: Written, Aug. 1986 W. Landsman, STX Corp. Use astrometry structure, W. Landsman Jan, 1994 Minor fix if bad Y range supplied W. Landsman Feb, 1996 Added /SILENT keyword W. Landsman March, 1997 Added ERRMSG keyword W. Landsman May 2000 Work for dimensions larger than 32767 W.L., M.Symeonidis Mar 2007 Added ALT keyword W.L. April 2007
(See $IDLUTILS_DIR/goddard/pro/astrom/hextract.pro)
HGREP
NAME: HGREP PURPOSE: Find a substring in a FITS header (or any other string array) CALLING SEQUENCE: HGREP, header, substring, [/KEEPCASE, /LINENUM ] INPUTS: header - FITS header or other string array substring - scalar string to find in header; if a numeric value is supplied, it will be converted to type string OPTIONAL INPUT KEYWORDS: /KEEPCASE: if set, then look for an exact match of the input substring Default is to ignore case . /LINENUM: if set, prints line number of header in which substring appears OUTPUTS: None, results are printed to screen EXAMPLE: Find every place in a FITS header that the word 'aperture' appears in lower case letters and print the element number of the header array: IDL> hgrep, header, 'aperture', /keepcase, /linenum HISTORY: Written, Wayne Landsman (Raytheon ITSS) August 1998 Adapted from STIS version by Phil Plait/ ACC November 14, 1997 Remove trailing spaces if a non-string is supplied W. Landsman Jun 2002
(See $IDLUTILS_DIR/goddard/pro/misc/hgrep.pro)
HISTOGAUSS
NAME: HISTOGAUSS PURPOSE: Histograms data and overlays it with a Gaussian. Draws the mean, sigma, and number of points on the plot. CALLING SEQUENCE: HISTOGAUSS, Sample, A, [XX, YY, GX, GY, /NOPLOT, /NOFIT, FONT=, CHARSIZE = ] INPUT: SAMPLE = Vector to be histogrammed OUTPUT ARGUMENTS: A = coefficients of the Gaussian fit: Height, mean, sigma A[0]= the height of the Gaussian A[1]= the mean A[2]= the standard deviation A[3]= the half-width of the 95% conf. interval of the standard mean A[4]= 1/(N-1)*total( (y-mean)/sigma)^2 ) = a measure of normality Below: superceded. The formula is not entirely reliable. A[4]= measure of the normality of the distribution. =1.0, perfectly normal. If no more than a few hundred points are input, there are formulae for the 90 and 95% confidence intervals of this quantity: M=ALOG10(N-1) ; N = number of points T90=ABS(.6376-1.1535*M+.1266*M^2) ; = 90% confidence interval IF N LT 50 THEN T95=ABS(-1.9065-2.5465*M+.5652*M^2) $ ELSE T95=ABS( 0.7824-1.1021*M+.1021*M^2) ;95% conf. (From Martinez, J. and Iglewicz, I., 1981, Biometrika, 68, 331-333.) XX = the X coordinates of the histogram bins (CENTER) YY = the Y coordinates of the histogram bins GX = the X coordinates of the Gaussian fit GY = the Y coordinates of the Gaussian fit OPTIONAL INPUT KEYWORDS: /NOPLOT - If set, nothing is drawn /FITIT If set, a Gaussian is actually fitted to the distribution. By default, a Gaussian with the same mean and sigma is drawn; the height is the only free parameter. CHARSIZE Size of the characters in the annotation. Default = 0.82. FONT - scalar font graphics keyword (-1,0 or 1) for text /WINDOW - set to plot to a resizeable graphics window _EXTRA - Any value keywords to the cgPLOT command (e.g. XTITLE) may also be passed to HISTOGAUSS SUBROUTINE CALLS: BIWEIGHT_MEAN, which determines the mean and std. dev. AUTOHIST, which draws the histogram GAUSSFIT() (IDL Library) which does just that REVISION HISTORY: Written, H. Freudenreich, STX, 12/89 More quantities returned in A, 2/94, HF Added NOPLOT keyword and print if Gaussian, 3/94 Stopped printing confidence limits on normality 3/31/94 HF Added CHARSIZE keyword, changed annotation format, 8/94 HF Simplified calculation of Gaussian height, 5/95 HF Convert to V5.0, use T_CVF instead of STUDENT_T, GAUSSFIT instead of FITAGAUSS W. Landsman April 2002 Correct call to T_CVF for calculation of A[3], 95% confidence interval P. Broos/W. Landsman July 2003 Allow FONT keyword to be passed. T. Robishaw Apr. 2006 Use Coyote Graphics for plotting W.L. Mar 2011 Better formatting of text output W.L. May 2012
(See $IDLUTILS_DIR/goddard/pro/robust/histogauss.pro)
HOR2EQ
NAME: HOR2EQ PURPOSE: Converts local horizon coords (alt-az) of something to equatorial (ra-dec). EXPLANATION: This is a nice code to calculate equatorial (ra,dec) coordinates from horizon (alt,az) coords. It is typically accurate to about 1 arcsecond or better (I have checked the output against the publicly available XEPHEM software). It performs precession, nutation, aberration, and refraction corrections. The perhaps best thing about it is that it can take arrays as inputs, in all variables and keywords EXCEPT Lat, lon, and Altitude (the code assumes these aren't changing), and uses vector arithmetic in every calculation except when calculating the precession matrices. CALLING SEQUENCE: HOR2EQ, alt, az, jd, ra, dec, [ha, LAT= , LON= , /WS, OBSNAME= , $ /B1950 , PRECESS_= 0, NUTATE_= 0, REFRACT_= 0, $ ABERRATION_= 0, ALTITUDE= , /VERBOSE, _EXTRA= ] INPUT VARIABLES alt : altitude (in degrees) [scalar or vector] az : azimuth angle (in degrees, measured EAST from NORTH, but see keyword WS below.) [scalar or vector] JD : Julian Date [scalar or vector], double precision Note: if RA and DEC are arrays, then alt and az will also be arrays. If RA and DEC are arrays, JD may be a scalar OR an array of the same dimensionality. OPTIONAL INPUT KEYWORDS: lat : north geodetic latitude of location in degrees lon : EAST longitude of location in degrees (Specify west longitude with a negative sign.) /WS : Set this to get the azimuth measured westward from south (not East of North). obsname : Set this to a valid observatory name to be used by the astrolib OBSERVATORY procedure, which will return the latitude and longitude to be used by this program. /B1950 : Set this if your ra and dec are specified in B1950, FK4 coordinates (instead of J2000, FK5) precess_ : Set this to 1 to force precession [default], 0 for no precession. nutate_ : Set this to 1 to force nutation [default], 0 for no nutation. aberration_ : Set this to 1 to force aberration correction [default], 0 for no correction. refract_ : Set to 1 to force refraction correction [default], 0 for no correction. altitude: The altitude of the observing location, in meters. [default=0]. /verbose: Set this for verbose output. The default is verbose=0. _extra: This is for setting TEMPERATURE or PRESSURE explicitly, which are used by CO_REFRACT to calculate the refraction effect of the atmosphere. If you don't set these, the program will make an intelligent guess as to what they are (taking into account your altitude). See CO_REFRACT for more details. OUTPUT VARIABLES ra : Right Ascension of object (J2000) in degrees (FK5); scalar or vector. dec : Declination of object (J2000) in degrees (FK5), scalar or vector. ha : hour angle (in degrees) (optional) DEPENDENCIES: NUTATE, PRECESS, ADSTRING(), SUNPOS, OBSERVATORY (from the astrolib) CO_NUTATE, CO_ABERRATION, CO_REFRACT, HADEC2ALTAZ BASIC STEPS Precess Ra-Dec to current equinox. Nutation Correction to Ra-Dec Aberration correction to Ra-Dec Calculate Local Mean Sidereal Time Calculate Local Apparent Sidereal Time Calculate Hour Angle Do Spherical Trig to find Apparent Alt-Az Apply refraction correction to find observed Alt. CORRECTIONS I DO NOT MAKE: * Deflection of Light by the sun due to GR. (typically milliarcseconds, can be arcseconds within one degree of the sun) * The Effect of Annual Parallax (typically < 1 arcsecond) * and more (see below) TO DO * Better Refraction Correction. Need to put in wavelength dependence, and integrate through the atmosphere. * Topocentric Parallax Correction (will take into account elevation of the observatory) * Proper Motion (but this will require crazy lookup tables or something). * Difference between UTC and UT1 in determining LAST -- is this important? * Effect of Annual Parallax (is this the same as topocentric Parallax?) * Polar Motion * Better connection to Julian Date Calculator. EXAMPLE: You are at Kitt Peak National Observatory, looking at a star at azimuth angle 264d 55m 06s and elevation 37d 54m 41s (in the visible). Today is Dec 25, 2041 and the local time is 10 PM precisely. What is the ra and dec (J2000) of the star you're looking at? The temperature here is about 0 Celsius, and the pressure is 781 millibars. The Julian date for this time is 2466879.7083333 IDL> hor2eq, ten(37,54,41), ten(264,55,06), 2466879.7083333d, ra, dec, $ /verb, obs='kpno', pres=781.0, temp=273.0 The program produces this output (because the VERBOSE keyword was set): Latitude = +31 57 48.0 Longitude = *** 36 0.0 ; longitude prints weirdly b/c of negative input to ADSTRING!! Julian Date = 2466879.708333 Az, El = 17 39 40.4 +37 54 41.0 (Observer Coords) Az, El = 17 39 40.4 +37 53 39.6 (Apparent Coords) LMST = +03 53 54.1 LAST = +03 53 53.6 Hour Angle = +03 38 30.1 (hh:mm:ss) Ra, Dec: 00 15 23.5 +15 25 1.9 (Apparent Coords) Ra, Dec: 00 15 24.2 +15 25 0.1 (J2041.9841) Ra, Dec: 00 13 14.1 +15 11 0.3 (J2000) The star is therefore Algenib! Compare the derived Ra, Dec with what XEPHEM got: Ra, Dec: 00 13 14.2 +15 11 1.0 (J2000) AUTHOR: Chris O'Dell Univ. of Wisconsin-Madison Observational Cosmology Laboratory Email: odell@cmb.physics.wisc.edu REVISION HISTORY: Made all integers type LONG W. Landsman September 2007 Fixed for case of scalar Julian date but vector positions W L June 2009
(See $IDLUTILS_DIR/goddard/pro/astro/hor2eq.pro)
HOST_TO_IEEE
NAME: HOST_TO_IEEE PURPOSE: Translate an IDL variable from host to IEEE representation EXPLANATION: The variable is converted from the format used by the host architecture into IEEE-754 representation ("big endian" as used, e.g., in FITS data ). Duplicates most of the functionality of the SWAP_ENDIAN_INPLACE procedure with the addition of the IDLTYPE keyword. CALLING SEQUENCE: HOST_TO_IEEE, data, [ IDLTYPE = ] INPUT-OUTPUT PARAMETERS: data - any IDL variable, scalar or vector. It will be modified by HOST_TO_IEEE to convert from host to IEEE representation. Byte and string variables are returned by HOST_TO_IEEE unchanged OPTIONAL KEYWORD INPUTS: IDLTYPE - scalar integer (1-15) specifying the IDL datatype according to the code given by the SIZE function. This keyword will usually be used when supplying a byte array that needs to be interpreted as another data type (e.g. FLOAT). EXAMPLE: Suppose FITARR is a 2880 element byte array to be converted to a FITS record and interpreted a FLOAT data. IDL> host_to_ieee, FITARR, IDLTYPE = 4 METHOD: The BYTEORDER procedure is called with the appropriate keywords MODIFICATION HISTORY: Adapted from CONV_UNIX_VAX, W. Landsman Hughes/STX January, 1992 Version for IDL V5.0 August 1997 Converted to IDL V5.0 W. Landsman September 1997 Added new integer datatypes C. Markwardt/W. Landsman July 2000 Use /SWAP_IF_LITTLE_ENDIAN keyword for 64bit types W. Landsman Feb 2003 Do not use XDR keywords to BYTEORDER for much improved speed W. Landsman April 2006
(See $IDLUTILS_DIR/goddard/pro/misc/host_to_ieee.pro)
HPRECESS
NAME: HPRECESS PURPOSE: Precess the astrometry in a FITS header to a new equinox CALLING SEQUENCE: HPRECESS, HDR, [ yearf ] INPUT-OUTPUT: HDR - FITS Header, must contain the CRVAL astrometry keywords, and either an EPOCH or EQUINOX keyword.