This page was created by the IDL library routine
mk_html_help. For more information on
this routine, refer to the IDL Online Help Navigator
or type:
? mk_html_help
at the IDL command line prompt.
Last modified: Sun Aug 5 17:03:06 2007.
NAME:
CONVERT_PRINCETON_HEADER2
PURPOSE:
Converts headers of data files written by Princeton Instruments'
WinSPEC and WinVIEW software into a structure
CATEGORY:
File input.
CALLING SEQUENCE:
hstruct = convert_princeton_header2(header)
INPUTS:
header:
byte Array[4100]. The first 4100 bytes of a P.I. data file
OUTPUTS:
hstruct - structure with header information
MODIFICATION HISTORY:
Modified from convert_princeton_header
(called by read_princeton, which was written by Mark Rivers)
Leslie Young (Southwest Research Institute) 08/05/07
changed name to convert_princeton_header2
- added documentation
- added interpretation of ROI structures
- added interpretation of Avalanche Gain info
(See convert_princeton_header2.pro)
NAME: isfile PURPOSE: Check if a file exists DESCRIPTION: CATEGORY: fileio CALLING SEQUENCE: exists = IsFile(fn) INPUTS: fn: the filename OPTIONAL INPUT PARAMETERS: KEYWORD INPUT PARAMETERS: OUTPUTS: exists (boolean): true if file exists KEYWORD OUTPUT PARAMETERS: COMMON BLOCKS: SIDE EFFECTS: RESTRICTIONS: PROCEDURE: call findfile MODIFICATION HISTORY: 2002/05/30 - Initial version written, Leslie Young SwRI
(See isfile.pro)
NAME: next_lun PURPOSE: find next available lun DESCRIPTION: find next available lun, useful for finding which code that fails to close opened luns. CATEGORY: fileio CALLING SEQUENCE: lun = next_lun() INPUTS: OPTIONAL INPUT PARAMETERS: KEYWORD INPUT PARAMETERS: OUTPUTS: Next available lun KEYWORD OUTPUT PARAMETERS: COMMON BLOCKS: SIDE EFFECTS: RESTRICTIONS: PROCEDURE: call get_lun, free_lun MODIFICATION HISTORY: 2002/05/30 - Initial version written, Leslie Young SwRI
(See next_lun.pro)
NAME:
nthline
PURPOSE: (one line)
Return the nth line in a file
DESCRIPTION:
Return the nth line in a file, using a lookup file called
filename.lookup .
CATEGORY:
File IO
CALLING SEQUENCE:
line = nthline(filename, linenum)
INPUTS:
filename - file from which to get lines
linenum - the line number to return (long or array of long)
OPTIONAL INPUT PARAMETERS:
None
KEYWORD INPUT PARAMETERS:
KEYWORD OUTPUT PARAMETERS:
OUTPUTS:
If input is a scalar, then output is a single string.
If input is a vector, then output is an array of strings.
If a line is not found (linenum out of range), returned value is ''.
COMMON BLOCKS:
None
SIDE EFFECTS:
None
PROCEDURES:
spawned call to sed
RESTRICTIONS:
Output file is different based on big vs. little-endian system.
For consistency, it is recommended that all files be written
big-endian. x86 Linux is this way, but OS X is not.
EXAMPLE:
print, nthline('foo',[430L, 1000L])
MODIFICATION HISTORY:
Written 23 Apr 2006 Leslie Young SwRI
Modified 26 Apr 2006 Henry Throop SwRI. Creates lookup file if it
does not exist. Improved other error handling.
2007 May 4 LAY swap if little endian
(See nthline.pro)
NAME: nthline PURPOSE: (one line) Return the nth line in a file DESCRIPTION: Return the nth line in a file CATEGORY: File IO CALLING SEQUENCE: line = nthline(filename, linenum) INPUTS: filename - file from which to get lines linenum - the line number to return (long or array of long) OPTIONAL INPUT PARAMETERS: None KEYWORD INPUT PARAMETERS: /VERBOSE -- If set, print diagnostics to screen. KEYWORD OUTPUT PARAMETERS: NSTARS -- Returns the number of successfully-retrieved lines. OUTPUTS: If input is a scalar, then output is a single string. If input is a vector, then output is an array of strings. If a line is not found (linenum out of range), returned value is ''. COMMON BLOCKS: None SIDE EFFECTS: None PROCEDURES: repeated calls to readf RESTRICTIONS: EXAMPLE: print, nthline(102,[430L, 1000L]) MODIFICATION HISTORY: Written 2006 Apr 23 Leslie Young SwRI
(See nthline_v1.pro)
NAME: nthline PURPOSE: (one line) Return the nth line in a file DESCRIPTION: Return the nth line in a file CATEGORY: File IO CALLING SEQUENCE: line = nthline(filename, linenum) INPUTS: filename - file from which to get lines linenum - the line number to return (long or array of long) OPTIONAL INPUT PARAMETERS: None KEYWORD INPUT PARAMETERS: /VERBOSE -- If set, print diagnostics to screen. KEYWORD OUTPUT PARAMETERS: NSTARS -- Returns the number of successfully-retrieved lines. OUTPUTS: If input is a scalar, then output is a single string. If input is a vector, then output is an array of strings. If a line is not found (linenum out of range), returned value is ''. COMMON BLOCKS: None SIDE EFFECTS: None PROCEDURES: spawned call to sed RESTRICTIONS: EXAMPLE: print, nthline(102,[430L, 1000L]) MODIFICATION HISTORY: Written 2006 Apr 23 Leslie Young SwRI
(See nthline_v2.pro)
NAME: nthline_lookup PURPOSE: (one line) make a lookup table for use by nthline DESCRIPTION: make a lookup table for use by nthline CATEGORY: File IO CALLING SEQUENCE: nthline_lookup, filename, lookup=lookup, recalc=recalc INPUTS: filename - file for which to make the lookup OPTIONAL INPUT PARAMETERS: KEYWORD INPUT PARAMETERS: lookup - name of lookup table (otherwise filename.lookup) recalc - if set, recalculate and save lookup table, even if file exists KEYWORD OUTPUT PARAMETERS: OUTPUTS: COMMON BLOCKS: None SIDE EFFECTS: Creates lookup table, a file of 2 x n longs startbyte nbyte PROCEDURES: RESTRICTIONS: EXAMPLE: MODIFICATION HISTORY: Written 2006 Apr 23 Leslie Young SwRI
(See nthline_lookup.pro)
NAME:
PRINCETON_HEADER__DEFINE
PURPOSE:
define the structures for princeton headers
CATEGORY:
File input.
CALLING SEQUENCE:
princeton_header__define
MODIFICATION HISTORY:
Modified from princeton_header__define
(called by read_princeton, which was written by Mark Rivers)
Leslie Young (Southwest Research Institute) 08/05/07
- added AvGainUsed, AvGain
(See princeton_header__define.pro)
NAME:
READ_PRINCETON
PURPOSE:
This procedure reads data files written by Princeton Instruments'
WinSPEC and WinVIEW software.
CATEGORY:
File input.
CALLING SEQUENCE:
READ_PRINCETON, File, Data
INPUTS:
File:
The name of the data file to read.
OUTPUTS:
Data[nx, ny, nframes]:
The output data array. The array will be 1, 2 or 3 dimensions
(depending upon whether ny and nframes are 1) and can be integer,
long or float data type.
KEYWORD OUTPUTS:
HEADER:
The 4100 byte header from the file. This header can be used to
extract additional information about the file. See the Princteon
Instruments "PC Interface Library Programming Manual" for the
description of the header structure, and this procedure for
examples of how to extract information from the header.
X_CALIBRATION:
An nx array of calibrated values for each pixel in the X direction.
Y_CALIBRATION:
An ny array of calibrated values for each pixel in the Y direction.
COMMENTS:
A 5-element string array containing the "experiment comments"
fields, which is a 5x80 byte array starting at location 200 in
the PI header. These fields are typically used to store
experiment-specific information. For example, in the tomography
experiments we use the first two strings to store the frame type
and rotation angle.
DATE:
A date string of the form DDMMMYYYY:HH:MM:SS
EXPOSURE:
The exposure time in seconds.
BACKGROUND_FILE:
The name of the background file that was subtracted from the data
RESTRICTIONS:
This procedure currently only extracts limited information from the
header. It should be exhanced to extract more fields, probably into a
structure.
The data and calibration are corrected for byte order when reading on
a big-endian host, but other elements of the header are not converted.
EXAMPLE:
Read a data file:
IDL> READ_PRINCETON, 'test.spe', data, header=header, x_cal=x_cal
IDL> plot, x_cal, data
IDL> clock_speed = float(header, 1428)
IDL> print, 'Vertical clock speed (microseconds) = ', clock_speed
MODIFICATION HISTORY:
Written by: Mark Rivers, 11/4/97
Mark Rivers 10/27/98 Convert data to long if any pixels are > 32K
Mark Rivers 11/12/98 Fix to not convert data if already long
Mark Rivers 3/16/99 Added /BLOCK keyword to openr to work with VMS
Mark Rivers 3/27/99 Added "Comments" keyword
Mark Rivers 3/29/99 Added "Date" keyword
Mark Rivers 2/22/00 Corrected byte order for data and calibration.
Mark Rivers 9/11/01 Added "exposure" keyword
Mark Rivers 9/12/01 Added "background_file" keyword
(See read_princeton.pro)
NAME:
READ_PRINCETON2
PURPOSE:
This procedure reads data files written by Princeton Instruments'
WinSPEC and WinVIEW software.
CATEGORY:
File input.
CALLING SEQUENCE:
READ_PRINCETON, File, Data
INPUTS:
File:
The name of the data file to read.
OUTPUTS:
Data[nx, ny, nframes]:
The output data array. The array will be 1, 2 or 3 dimensions
(depending upon whether ny and nframes are 1) and can be integer,
long or float data type.
KEYWORD OUTPUTS:
HEADER:
The 4100 byte header from the file. This header can be used to
extract additional information about the file. See the Princteon
Instruments "PC Interface Library Programming Manual" for the
description of the header structure, and this procedure for
examples of how to extract information from the header.
X_CALIBRATION:
An nx array of calibrated values for each pixel in the X direction.
Y_CALIBRATION:
An ny array of calibrated values for each pixel in the Y direction.
COMMENTS:
A 5-element string array containing the "experiment comments"
fields, which is a 5x80 byte array starting at location 200 in
the PI header. These fields are typically used to store
experiment-specific information. For example, in the tomography
experiments we use the first two strings to store the frame type
and rotation angle.
DATE:
A date string of the form DDMMMYYYY:HH:MM:SS
RESTRICTIONS:
This procedure currently only extracts limited information from the
header. It should be exhanced to extract more fields, probably into a
structure.
The data and calibration are corrected for byte order when reading on
a big-endian host, but other elements of the header are not converted.
EXAMPLE:
Read a data file:
IDL> READ_PRINCETON, 'test.spe', data, header=header, x_cal=x_cal
IDL> plot, x_cal, data
IDL> clock_speed = float(header, 1428)
IDL> print, 'Vertical clock speed (microseconds) = ', clock_speed
MODIFICATION HISTORY:
Written by: Mark Rivers, 11/4/97
Mark Rivers 10/27/98 Convert data to long if any pixels are > 32K
Mark Rivers 11/12/98 Fix to not convert data if already long
Mark Rivers 3/16/99 Added /BLOCK keyword to openr to work with VMS
Mark Rivers 3/27/99 Added "Comments" keyword
Mark Rivers 3/29/99 Added "Date" keyword
Mark Rivers 2/22/00 Corrected byte order for data and calibration.
Roban Kramer 7/13/2001 roban@sccs.swarthmore.edu, changed
data_type=2 to use
data = intarr(nx, ny, nframes)
Added "exposure" structure
(See read_princeton2.pro)
NAME:
READ_PRINCETON_GZ
PURPOSE:
This procedure reads data files written by Princeton Instruments'
WinSPEC and WinVIEW software.
CATEGORY:
File input.
CALLING SEQUENCE:
READ_PRINCETON, File, Data
INPUTS:
File:
The name of the data file to read.
KEYWORD INPUTS:
compress=compress
0 if uncompressed, 1 if compressed (see compress keyword to open)
-1 to determine compression from the filename
nodata = nodata
1 if routine should read the header only
OUTPUTS:
Data[nx, ny, nframes]:
The output data array. The array will be 1, 2 or 3 dimensions
(depending upon whether ny and nframes are 1) and can be integer,
long or float data type.
KEYWORD OUTPUTS:
HEADER:
The 4100 byte header from the file. This header can be used to
extract additional information about the file. See the Princteon
Instruments "PC Interface Library Programming Manual" for the
description of the header structure, and this procedure for
examples of how to extract information from the header.
X_CALIBRATION:
An nx array of calibrated values for each pixel in the X direction.
Y_CALIBRATION:
An ny array of calibrated values for each pixel in the Y direction.
COMMENTS:
A 5-element string array containing the "experiment comments"
fields, which is a 5x80 byte array starting at location 200 in
the PI header. These fields are typically used to store
experiment-specific information. For example, in the tomography
experiments we use the first two strings to store the frame type
and rotation angle.
DATE:
A date string of the form DDMMMYYYY:HH:MM:SS
EXPOSURE:
The exposure time in seconds.
BACKGROUND_FILE:
The name of the background file that was subtracted from the data
RESTRICTIONS:
This procedure currently only extracts limited information from the
header. It should be exhanced to extract more fields, probably into a
structure.
The data and calibration are corrected for byte order when reading on
a big-endian host, but other elements of the header are not converted.
EXAMPLE:
Read a data file:
IDL> READ_PRINCETON, 'test.spe', data, header=header, x_cal=x_cal
IDL> plot, x_cal, data
IDL> clock_speed = float(header, 1428)
IDL> print, 'Vertical clock speed (microseconds) = ', clock_speed
MODIFICATION HISTORY:
Written by: Mark Rivers, 11/4/97
Mark Rivers 10/27/98 Convert data to long if any pixels are > 32K
Mark Rivers 11/12/98 Fix to not convert data if already long
Mark Rivers 3/16/99 Added /BLOCK keyword to openr to work with VMS
Mark Rivers 3/27/99 Added "Comments" keyword
Mark Rivers 3/29/99 Added "Date" keyword
Mark Rivers 2/22/00 Corrected byte order for data and calibration.
Mark Rivers 9/11/01 Added "exposure" keyword
Mark Rivers 9/12/01 Added "background_file" keyword
Leslie Young (Southwest Research Institute) 08/05/07
changed name to read_princeton_gz
- allows reading of gzipped files
- calls convert_princeton_header2 for more complete interpretation
of header
- added nodota input keyword
(See read_princeton_gz.pro)
NAME:
spe_filenames
PURPOSE: (one line)
return a list of SPE filenames
DESCRIPTION:
Given a list of indices, return a list of filenames
CATEGORY:
File IO
CALLING SEQUENCE:
filenames = spe_filenames(indxarr, prefix=prefix, dir=dir,
silent=silent, found=found)
INPUTS:
indxarr : array of ints or longs
INPUT KEYWORDS:
prefix : prefix ("Data File Name" in WinView). Default = 'im'
dir : data directory (with terminal '/'). Default = ''
silent : if set, then do not print out error messages
OUTPUTS:
A list of filenames, same length at indices
Filenames are searched in this order
[dir][pre]i.SPE
[dir][pre]i.spe
[dir][pre]i.SPE.gz
[dir][pre]i.spe.gz
if not found, file is '[dir][pre]i.spe not found'
OUTPUT KEYWORDS:
found : array with 1 if file found, 0 if not found
EXAMPLE:
dir = '/Volumes/DOC160GB/20070318_P445.3/RBO/2007MAR18/'
print, spe_filenames([10,11,12],pre='im', dir=dir)
MODIFICATION HISTORY:
Written 14 Jun 2007 Leslie Young SwRI
(See spe_filenames.pro)
NAME:
spe_head2fits
PURPOSE: (one line)
convert a Princeton Instruments SPE header structure to a FITS header
CATEGORY:
File IO
CALLING SEQUENCE:
fitsh = spe_head2fits(speh, infitsh=infitsh)
INPUTS:
speh : structure for the header of Princeton Instruments
WinView or WinSpec programs, as output by
convert_princeton_header2
INPUT KEYWORDS:
infitsh = initial FITS header
OUTPUTS:
fitsh = output FITS header
MODIFICATION HISTORY:
Written 05 Aug 2007 Leslie Young SwRI
(See spe_head2fits.pro)
NAME:
TMPPRO
PURPOSE:
Get the filename and path of a temporary .pro file.
CATEGORY:
IO.
CALLING SEQUENCE:
Result = TMPPRO( [Prefix, Ndigits] )
OPTIONAL INPUTS:
Prefix: The prefix of the filename, ('tmp'=default).
Ndigits: The number of digits to append to the Prefix, (3=default).
OPTIONAL INPUT KEYWORD PARAMETERS:
SEED: The seed used by the random number generator to determine
the number to append to the Prefix.
OUTPUTS:
The file specification returned is:
tmp_dir+Prefix+NNN+Suffix
where NNN is a random LONG integer with number of digits = Ndigits.
This routine also searches the tmp_dir for this filename. If a
duplicate filename is found, then another random number is chosen.
tmp_dir is the path to the /tmp directory
where is the directory containing tmppro
EXAMPLE:
Let's create a temp filename myNNNN.pro:
tmp_file = TMPFILE('my',4)
MODIFICATION HISTORY:
30-DEC-2005 Modified from tmpfile by Leslie Young, SwRI
MODIFICATION HISTORY OF TMPFILE
Written by: Han Wen, November 1994.
08-FEB-1995 Fixed minor bug, random integer -> random LONG integer
12-JUN-1995 Check existence of TMP directory and create it if no
such directory exists.
01-JUL-1995 Use DIR_EXIST to check existence of TMP directory.
07-AUG-1996 Use TMPPATH (hacked version of FILEPATH) to determine
TMP directory.
(See tmppro.pro)