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: Mon Jun 20 10:33:01 2005.
NAME:
CALC_STXM5
PURPOSE:
This procedure calculates calibrated data signals,
fast/slow_dist_um arrays and other necessary stuff from an sm_par
structure and the raw data array.
It is called by read_stxm5.pro when reading a local STXM 5 data
file, and from sm_gui.pro when STXM 5 data is transferred from
the server (over the socket).
AUTHOR:
Benjamin Hornberger
benjamin.hornberger@stonybrook.edu
CATEGORY:
STXM 5
CALLING SEQUENCE:
CALC_STXM5, sm_par, khz, fast_dist_um, slow_dist_um, $
image_data_khz=image_data_khz, $
image_data_raw=image_data_raw, $
image_data_intraw=image_data_intraw, $
disp_name=disp_name, $
i_clock=i_clock, $
i_counter=i_counter, $
i_first_sidet_channel=i_first_sidet_channel, $
n_rec_sidet_channels=n_rec_sidet_channels, $
/verbose, n_slow_pixels=n_slow_pixels
INPUT PARAMETERS:
sm_par: The sm_par structure.
INPUT KEYWORDS:
IMAGE_DATA_INTRAW: The raw STXM 5 image data as an [n_fast_pixels,
n_slow_pixels, n_data] 3-dimensional array of unsigned 16 bit
integers. Required. Must be 3-d.
DISP_NAME: String holding the signal which is supposed to be
returned in the Khz variable. If not given, sm_par.disp_name
is used. This string is usually one out of the list of
predefined combinations as defined in stxm5_displays.pro. In
this case, the signal will be any linear combination of
calibrated detector signals. Do "stxm5_displays, /list" for a
list of allowed signals (linear combinations). This
corresponds to a choice of "Predefined Combinations" in
sm_gui.
Otherwise, DISP_NAME can be string like 'XX::YY', where XX is
either 'Predefined Combinations', 'Raw Integer', 'Raw
Counts / mVolts' or 'Calibrated kHz'. This part of the
string describes the signal type, like in the upper droplist
in sm_gui. The second part (YY) is either one of the allowed
predefined combinations (as in the above paragraph) or one
detector channel in case of the three other signal types.
See the STXM 5 manual (chapter about display concept) for more
information. All string comparisons are case-insensitive.
VERBOSE: Print more messages.
N_SLOW_PIXELS: If this keyword is set, it overwrites
sm_par.n_slow_pixels. Note that this number still has to
correspond to the size of the second dimension in
IMAGE_DATA_INTRAW. This is used during live update, when only
one new scan line is calculated.
NO_INVALID_DISP_NAME_ERROR: The kHz array is calculated according
to the keyword DISP_NAME, or to sm_par.disp_name. If that
disp_name is invalid, a non-fatal error is issued, and the kHz
array will be undefined. Set this keyword to suppress this
error. This is necessary in sm_gui, when the scan data is
initialized for a new scan. At that point, sm_par.disp_name is
not yet set, and we don't want to issue that error (we
disregard the khz array at that point anyway.
OUTPUT PARAMETERS:
Khz: The calibrated image data as a 2-dimensional float
array. Depends on the setting of the DISP_NAME keyword.
Fast_dist_um, Slow_dist_um: 1-dimensional double arrays holding
the position of each scan pixel on the fast and slow axes is
microns (stage positions in the microscope)
OUTPUT KEYWORDS:
EV: Set this keyword to a named variable which will contain the
scan energy. If one of the scan axis was the monochromator
(e.g., the fast axis for simple point spectra), this will be
an array.
IMAGE_DATA_KHZ: Floating point array of the same dimensions as
IMAGE_DATA_INTRAW which holds the calibrated scan
signals. Proportional counter channels and silicon detector
channels hold the count rate in kHz (where the silicon
detector channels were calibrated according to the calibration
parameters in sm_par), the clock channel holds the dwell time
for each scan pixel in milliseconds, and all ADC channels
which are not silicon detector channels hold their signal in
mVolts.
IMAGE_DATA_RAW: Floating point array of the same dimensions as
IMAGE_DATA_INTRAW which holds the raw scan signals. That's the
counts from the scaler, corrected for any divideby, and mVolts
from ADC channels.
I_CLOCK: Index of the clock signal in the third dimension of the
data arrays. -1 if the clock was not recorded.
I_COUNTER: Index of the proportional counter signal in the third
dimension of the data arrays. -1 if the counter was not
recorded.
I_FIRST_SIDET_CHANNEL: Index of the first silicon detector channel
in the third dimension of the data arrays. -1 if no silicon
detector channel was recorded. NOTE: All silicon detector
channels must be adjacent to each other!
N_REC_SIDET_CHANNELS: Number of recorded silicon detector
channels.
REQUIREMENTS:
Better don't try to use this without having the entire
xray1 idl_local CVS repository available.
PROCEDURE:
Normally, this procedure is called with all available parameters
and keywords, except /VERBOSE and possibly DISP_NAME.
MODIFICATION HISTORY:
Written: BH 2004-09-24, extracted from read_stxm5.pro
2004-11-18 BH: set all zeroes in the dwell_ms array to 1
2005-03-03 BH: Introduce some arg_present() checks to avoid
unnecessary calculations; change calculation of kHz array
from loop to array operation. No speed gain,
unfortunately.
2005-03-03 BH: Add keyword N_SLOW_PIXELS so that the routine
can be called on fewer scan lines than a whole scan
(specifically, only one scan line during live update)
2005-03-07 BH: Add keyword NO_INVALID_DISP_NAME_ERROR
2005-03-15 BH: Add another reform() call in calculation of khz
array because once again IDL lost a trailing dimension of
size 1.
2005-04-09 BH: Changed calculation of khz array so that not
only predefined combinations can be returned, but also
slices from the raw integer, raw counts / mvolts or
calibrated khz arrays. In this case, disp_name must be
something like "Calibrated kHz::Sidet01"
2005-06-10 BH: Added keyword EV, updated documentation
(See calc_stxm5.pro)
NAME:
READ_STXM5
PURPOSE:
This procedure reads STXM 5 data files on the IDL command line.
AUTHOR:
Benjamin Hornberger
benjamin.hornberger@stonybrook.edu
CATEGORY:
STXM 5
CALLING SEQUENCE:
READ_STXM5, filename, sm_par, khz, fast_dist_um, slow_dist_um
INPUT PARAMETERS:
filename: Name (including path, if necessary) of the STXM 5 data
file to read.
INPUT KEYWORDS:
DISP_NAME: String holding the signal which is supposed to be
returned in the Khz variable. If not given, sm_par.disp_name
is used. This string is usually one out of the list of
predefined combinations as defined in stxm5_displays.pro. In
this case, the signal will be any linear combination of
calibrated detector signals. Do "stxm5_displays, /list" for a
list of allowed signals (linear combinations). This
corresponds to a choice of "Predefined Combinations" in
sm_gui.
Otherwise, DISP_NAME can be string like 'XX::YY', where XX is
either 'Predefined Combinations', 'Raw Integer', 'Raw
Counts / mVolts' or 'Calibrated kHz'. This part of the
string describes the signal type, like in the upper droplist
in sm_gui. The second part (YY) is either one of the allowed
predefined combinations (as in the above paragraph) or one
detector channel in case of the three other signal types.
See the STXM 5 manual (chapter about display concept) for more
information. All string comparisons are case-insensitive.
HEADER_ONLY: Set this keyword to read only the sm_par structure,
not the scan data.
HELP: Set this keyword to print out usage information for this
procedure.
VERBOSE: Display more messages.
NO_INVALID_DISP_NAME_ERROR: The kHz array is calculated according
to the keyword DISP_NAME, or to sm_par.disp_name. If that
disp_name is invalid, a non-fatal error is issued, and the kHz
array will be undefined. Set this keyword to suppress this
error. This is necessary in sm_gui, when the scan data is
initialized for a new scan. At that point, sm_par.disp_name is
not yet set, and we don't want to issue that error (we
disregard the khz array at that point anyway.
OUTPUT PARAMETERS:
sm_par: The sm_par structure which holds all kinds of important
scan parameters. See the STXM 5 documentation for the meaning
of each parameter.
khz: The calibrated image data as a 2-dimensional float
array. Depends on the setting of the DISP_NAME keyword.
OPTIONAL OUTPUT PARAMETERS:
fast_dist_um, slow_dist_um: 1-dimensional double arrays holding
the position of each scan pixel on the fast and slow axes is
microns (stage positions in the microscope). For an eV axis,
this is the wavelength in microns.
OUTPUT KEYWORDS:
EV: Set this keyword to a named variable which will contain the
scan energy. If one of the scan axis was the monochromator
(e.g., the fast axis for simple point spectra), this will be
an array.
IMAGE_DATA_KHZ: Floating point array [n_fast_pixels,
n_slow_pixels, n_data] which holds the calibrated scan
signals. Proportional counter channels and silicon detector
channels hold the count rate in kHz (where the silicon
detector channels were calibrated according to the calibration
parameters in sm_par), the clock channel holds the dwell time
for each scan pixel in milliseconds, and all ADC channels
which are not silicon detector channels hold their signal in
mVolts.
IMAGE_DATA_RAW: Floating point array of the same dimensions as
IMAGE_DATA_KHZ which holds the raw scan signals. That's the
counts from the scaler, corrected for any divideby, and mVolts
from ADC channels.
IMAGE_DATA_INTRAW: 16-bit unsigned integer array of the same
dimensions as IMAGE_DATA_KHZ which holds the raw scan data.
I_CLOCK: Index of the clock signal in the third dimension of the
data arrays. -1 if the clock was not recorded.
I_COUNTER: Index of the proportional counter signal in the third
dimension of the data arrays. -1 if the counter was not
recorded.
I_FIRST_SIDET_CHANNEL: Index of the first silicon detector channel
in the third dimension of the data arrays. -1 if no silicon
detector channel was recorded. NOTE: All silicon detector
channels must be adjacent to each other!
N_REC_SIDET_CHANNELS: Number of recorded silicon detector
channels.
HANDLING ERRORS:
read_stxm5 will throw an error if the file can't be read
properly. End-user routines which use read_stxm5.pro are
encouraged to use CATCH error handlers, e.g. like this:
catch, error
IF error NE 0 THEN BEGIN
catch, /cancel
ok = dialog_message(['Dear User: ', $
'I'm awfully sorry to tell you that ', $
'this file could not be read properly.', $
'My apologies. '], /error)
return
ENDIF
read_stxm5, file, sm_par, khz
catch, /cancel
RESTRICTIONS:
Better don't try to use this without the entire xray1
idl_local CVS repository available.
EXAMPLE:
IDL> pick, datafile
IDL> read_stxm5, datafile, sm_par, khz
IDL> tvscl, khz
MODIFICATION HISTORY:
Written: BH 2004-03-29, adapted from read_sm.pro
BH 2004-06-15: unknown changes
BH 2004-09-24: cut out a lot of code and create
calc_stxm5.pro.
BH 2005-03-01: Add keyword SUCCESS
BH 2005-03-02: Changed error handling. read_stxm5 now throws
an error if the file can't be read. Routines which
use read_stxm5.pro are encouraged to use a catch error
handler to catch errors from read_stxm5.pro.
BH 2005-03-02: Removed keyword SUCCESS because it's
unnecessary with the improved error handling
BH 2005-03-25: Added sm_par.[x,y,z]_laser_positions for
filever >= 6
HF 2005-03-29: Added sm_par.drift_d[x,y]_over_dz and
sm_par.zstg_follows_spectrum for filever >= 6
BH 2005-05-12: Added keyword NO_INVALID_DISP_NAME_ERROR which
is just passed through to calc_stxm5.pro
BH 2005-06-10: Added keyword EV, updated documentation.
(See read_stxm5.pro)
NAME:
SM_IPAR_STXM5
PURPOSE:
Initializes the STXM 5 sm_par structure
AUTHOR:
Benjamin Hornberger
benjamin.hornberger@stonybrook.edu
CATEGORY:
STXM 5
CALLING SEQUENCE:
SM_IPAR_STXM5, sm_par
INPUTS PARAMETERS:
None.
INPUT KEYWORDS:
SM_PAR_N_ADC_CHANNELS: Number of ADC channels. Default: 16, as
read from stxm_define.pro
SM_PAR_N_SCALER_CHANNELS: Number of Scaler channels. Default: 2,
as read from stxm_define.pro
SM_PAR_MAXPOINTLIST: Maximum number of entries in the
pointlist. Default: 25, as read from stxm_define.pro
SM_PAR_STRLEN: String length for text entries. Default: 128, as
read from stxm_define.pro
OUTPUTS:
sm_par: The sm_par structure returned.
MODIFICATION HISTORY:
Written: BH 2004-02-10
BH 2004-06-14, 2004-10-26: unknown changes
BH 2005-03-25: add members x,y,z_use_laser_positions
HF 2005-03-29: add members drift_dx/y_over_dz, zstg_follows_spectrum
(See sm_ipar_stxm5.pro)
NAME:
STXM5_DISPLAYS
PURPOSE:
This procedure defines available displays as linear combinations
of calibrated (!) image_data channels for STXM 5.
AUTHOR:
Benjamin Hornberger
benjamin.hornberger@stonybrook.edu
CATEGORY:
STXM 5
CALLING SEQUENCE:
STXM5_DISPLAYS, Pixel_channel_names, $
Disp_names, $
Linear_combinations
INPUT PARAMETERS:
Pixel_channel_names: Required unless /LIST_ONLY is set. String
array of pixel channel names from sm_par.
INPUT KEYWORDS:
LIST_ONLY: Set this keyword if you only want to have a list of
allowed display names printed.
NO_OUTPUT: Set to suppress warnings.
HELP: Display help and exit.
OUTPUT PARAMETERS:
Disp_names: String array with short names for displays
Linear_combinations: Floating point array [n_data, n_displays]
which holds the linear combinations. Each line in this array
holds all the coefficients to calculate the corresponding
display as linear combination from all data channels.
OUTPUT KEYWORDS:
LONG_NAMES: String array holding long names for the displays.
NONZEROES: Array holding the indices of those displays where not
all coefficients are zero.
N_NONZEROES: Number of displays in the list for which not all
coefficients are zero.
EXAMPLE:
To calculate an array with all interesting display combinations
from a STXM 5 data file:
IDL> read_stxm5, file, sm_par, image_data_khz=image_data_khz
IDL> stxm5_displays, sm_par.pixel_channel_names, disp_names, $
linear_combinations, nonzeroes=nonzeroes, $
n_nonzeroes=n_nonzeroes
IDL> displays=fltarr(sm_par.n_fast_pixels, $
sm_par.n_slow_pixels, n_nonzeroes)
IDL> FOR i=0, n_nonzeroes-1 DO $
FOR j=0, sm_par.n_data-1 DO displays[*, *, i] = $
displays[*, *, i] + linear_combinations[j, nonzeroes[i]] * $
image_data_khz[*, *, j]
MODIFICATION HISTORY:
Written: BH 2004-03-23
BH 2004-10-27: Major changes. Now use pixel_channel_names to
determine combinations rather than i_counter, i_clock,
i_first_sidet_channel and n_sidet_channels -
BH 2005-06-07: Added displays for APS 2-ID-B data files
(See stxm5_displays.pro)
NAME:
STXM5_DIST_UM
PURPOSE:
This function calculates the fast/slow_dist_um arrays which hold,
for a STXM 5 scan, the microscope position in microns for each
scan pixel on the fast and slow scan axes.
AUTHOR:
Benjamin Hornberger
benjamin.hornberger@stonybrook.edu
CATEGORY:
STXM 5
CALLING SEQUENCE:
Result = STXM5_DIST_UM(Sm_par)
RETURN VALUE:
Fast_dist_um array as 1-dimensional double array. If the keyword
/SLOW is set, slow_dist_um will be returned.
INPUTS:
Sm_par: sm_par structure from which the array can be
calculated. The center positions, number of pixels, pixel size
etc. are used to determine the output.
INPUT KEYWORDS:
SLOW: Set this keyword to return the slow_dist_um array rather
than the fast_dist_um array.
RESTRICTIONS:
Needs the STXM_DEVICE() and EV2NM() functions.
MODIFICATION HISTORY:
Written: BH 2004-07-01
BH 2005-03-22: changed error handling
(See stxm5_dist_um.pro)
NAME:
STXM_DEFINE
PURPOSE:
This file defines some "global STXM 5 constants", like the
DEFINEs in sm_par.h on the C++ side.
This file can be processed as a batch or include file via
"@stxm_define" whenever you need these constants.
AUTHOR:
Benjamin Hornberger
benjamin.hornberger@stonybrook.edu
CATEGORY:
STXM 5
CALLING SEQUENCE:
@stxm_define
INPUT / OUTPUT PARAMETERS:
None! This is a batch file, not a procedure.
REQUIREMENTS:
You must make sure that the variables and device enumerations are
in sync with sm_par.h on the C++ side.
MODIFICATION HISTORY:
Written: BH 2004-??-??
(See stxm_define.pro)
NAME:
STXM_DETECTOR
PURPOSE:
This function returns the STXM 5 detector name when a detector
number is passed, and vice versa.
AUTHOR:
Benjamin Hornberger
benjamin.hornberger@stonybrook.edu
CATEGORY:
STXM 5
CALLING SEQUENCE:
result = STXM_DETECTOR(Detector)
RETURN VALUE:
If a string is given as input, the corresponding detector number
is returned. If a number is given as input, the name is returned
as string.
INPUTS:
None.
OUTPUT KEYWORDS:
LONG_NAME: Will return the long detector name.
RESTRICTIONS:
Needs stxm_define.pro
MODIFICATION HISTORY:
Written: BH 2004-09-10
(See stxm_detector.pro)
NAME:
STXM_DEVICE
PURPOSE:
This function returns the STXM 5 device name when a device number
is passed, and vice versa.
AUTHOR:
Benjamin Hornberger
benjamin.hornberger@stonybrook.edu
CATEGORY:
STXM 5
CALLING SEQUENCE:
result = STXM_DEVICE(Device)
RETURN VALUE:
If a string is given as input, the corresponding device number is
returned. If a number is given as input, the name is returned as
a string.
INPUTS:
None.
OUTPUT KEYWORDS:
LONG_NAME: Will return the long device name.
RESTRICTIONS:
Needs stxm_define.pro
MODIFICATION HISTORY:
Written: BH 2004-09-09
(See stxm_device.pro)
NAME:
STXM_FILENAME
PURPOSE:
This function splits a valid STXM 4 or STXM 5 filename into its
parts: microscope, year, month, day and number of scan for that
day. It can either return a structure holding all this
information, or single pieces of information depending on the
keywords set.
Valid STXM 4 filenames look like 'x1aos_23jan2003_0010.sm'
Valid STXM 5 filenames look like 'x1ais_20050123_0123.sm'
Valid microscope specifiers are 'x1aos', 'x1ais' and 'x1aic'
AUTHOR:
Benjamin Hornberger
benjamin.hornberger@stonybrook.edu
CATEGORY:
STXM, Beamline
CALLING SEQUENCE:
Result = STXM_FILENAME(Filename)
RETURN VALUE:
If no keyword is set, the function returns an anonymous structure
with the following fields:
microscope: 5-character string ('x1aos', 'x1ais', or 'x1aic')
year: integer number
month: integer number (1 ... 12)
day: integer number (1 ... 31)
scannum: integer number
stxmver: STXM version (4 or 5). The distinction is solely
made from the syntax of the filename
date: Date of the scan as ASCII date/time string as
returned from the SYSTIME() function
('DOW MON DD HH:MM:SS YYYY'). All time entries are
set to zero.
If Filename doesn't fulfill STXM 4 or STXM 5 scan file
naming conventions, all string fields will be empty strings, and
all integer fields will be zero.
INPUT PARAMETERS:
Filename: STXM 4 or STXM 5 file name. The function will first use
the FILE_BASENAME() function to cut off any path. If Filename
doesn't follow STXM 4 or STXM 5 naming conventions, zeroes and
empty strings will be returned.
INPUT KEYWORDS:
MICROSCOPE: If this keyword is set, the function will return the
microscope specifier as a string.
YEAR: If this keyword is set, the function will return the year
of the scan as an integer number.
MONTH: If this keyword is set, the function will return the month
of the scan as an integer number (1 ... 12).
DAY: If this keyword is set, the function will return the day of
the scan as an integer number (1 ... 31).
SCANNUM: If this keyword is set, the function will return the
scan number as integer.
DATE: If this keyword is set, the function will return the date
of the scan as ASCII date/time string (as returned from
SYSTIME()). The format is 'DOW MON DD HH:MM:SS YYYY'. All time
entries are set to zero.
RESTRICTIONS:
This function requires several date/time functions or procedures
from the JHUAPL IDL library
(http://fermi.jhuapl.edu/s1r/idl/s1rlib/local_idl.html).
EXAMPLE:
IDL> filename = 'x1ais_20050211_0220.sm'
IDL> help, stxm_filename(filename), /struct
** Structure <56d5258>, 7 tags, length=36, data length=34, refs=1:
MICROSCOPE STRING 'x1ais'
YEAR INT 2005
MONTH INT 2
DAY INT 11
SCANNUM INT 220
STXMVER INT 5
DATE STRING 'Fri Feb 11 00:00:00 2005'
IDL> print, stxm_filename(filename, /microscope)
x1ais
MODIFICATION HISTORY:
Written: 2005-02-11 BH.
BH 2005-06-20: Include FILE_BASENAME() call to first cut off any
path.
(See stxm_filename.pro)
NAME:
STXM_FILEVER
PURPOSE:
This function returns the STXM file version as an integer
number.
AUTHOR:
Benjamin Hornberger
benjamin.hornberger@stonybrook.edu
CATEGORY:
STXM
CALLING SEQUENCE:
Result = STXM_FILEVER(Filename)
RETURN VALUE:
The function returns the STXM file version as a long integer
number.
INPUTS:
Filename: Name (plus path) of the file to be checked.
RESTRICTIONS:
The function just checks if it can read the global attribute
'filever' from the netCDF file. This is not a perfect proof of a
valid STXM data file, but it's quite safe.
MODIFICATION HISTORY:
Written: BH 2004-03-25
BH 2005-03-01: Cleaned up quite a bit.
BH 2005-06-20: Changed error handling
(See stxm_filever.pro)
NAME:
WRITE_STXM5
PURPOSE:
This procedure writes a STXM 5 data file.
AUTHOR:
Benjamin Hornberger
benjamin.hornberger@stonybrook.edu
CATEGORY:
STXM 5
CALLING SEQUENCE:
WRITE_STXM5, filename, sm_par, image_data
INPUT PARAMETERS:
filename: Name of the STXM 5 data file to write. Should have an
".sm" extension.
sm_par: sm_par structure to write to the file.
image_data: Raw STXM 5 scan data to write to the file. Must be an
[n_fast_pixels, n_slow_pixels, n_data] 3-dimensional array of
16-bit signet or unsigned integers.
INPUT KEYWORDS:
HELP: Print help and exit.
OVERWRITE: Set this keyword to overwrite the file in case it
exists already. Caution: There is no warning!
MODIFICATION HISTORY:
BH 2004-??-??, written, adapted from write_sm.pro
BH 2004-06-15: unknown changes
BH 2004-06-30: throw out fast/slow_dist_um arrays. Will be
calculated from center, number of pixels and pixel size in
the future.
BH 2005-03-02: Added keyword OVERWRITE. Removed keyword
SUCCESS. All image_data to be of type UINT (in addition to
INT).
BH 2005-03-02: Improved error handling. write_stxm5 now throws
an error if something goes wrong.
BH 2005-03-25: Added sm_par.[x,y,z]_use_laser_positions
(filever >= 6)
HF 2005-03-29: Added sm_par.drift_d[x,y]_over_dz and
sm_par.zstg_follows_spectrum for filever >= 6
(See write_stxm5.pro)