C program

Spd is the backend used by the fable preprocessor to correct images. It is written in C and is maintained by Rainer Wilcke. It was originally written by Jorg Klora. The fable preprocessor calls spd via its command line interface. Spd has many options and they can be seen by running spd without any arguments on the command line :

Usage

./spd parameter=option [filenames]
src_id source image shared memory id>
src_ext source image file extension (default none)
cor_id shared memory id of corrected image
cor_ext corrected img. file extension (default none)
dark_id dark image shared memory id
dark_file dark image file name
dark_const value subtract constant dark image value (default: no dark image subtraction done)
dark_ext dark image file extension (default none)
do_dark 0|1 if 0, suppress dark image correction (default 1)
save_dark 0|1|2 save dark image memory to file (default 2)
inp_const add input image constant (default 0).
inp_exp apply exponent to input image (default 1).
inp_factor value multiply with input image factor (default 1).
flood_id flood field image shared memory id
flood_file flood field image file name (default: no floodfield used)
bckg_id scattering background image shared memory id
bckg_file scattering background image file name (default: no scattering background used)
bckg_const additive scattering constant(default 0).
bckg_fact constant scattering factor (default 1).
header_id shared memory id for data header (default: not used)
pass 0|1 pass input file header to output (default 0)
header_min minimum header length for output file(default 0)
header_ext extension for header output file (default none)
distortion_file file(default "spatial.dat")
xfile file (x distortion read from edf file)
yfile file (y distortion read from edf file)
xoutfile file (x distortion saved to edf file)
youtfile file(y distortion saved to edf file)
active_radius value (values outside will not be corrected)
psize_distort 0|1|2 take image params from distortion file 0: none, 1: pix, 2: pix, cen, dis, proj, rot (default 0)
cen_1 xxx if set, defines Center_1 header value
cen_2 xxx if set, defines Center_2 header value
i0 xxx if set, defines Intensity0 header value
i1 xxx if set, defines Intensity1 header value
off_1 = xxx if set, defines Offset_1 header value
off_2 xxx if set, defines Offset_2 header value
pix_1 xxx if set, defines PSize_1 header value
pix_2 xxx if set, defines PSize_2 header value
bis_1 xxx if set, defines BSize_1 header value
bis_2 xxx if set, defines BSize_2 header value
dis xxx if set, defines SampleDistance header value
ori xxx if set, defines RasterOrientation header value
tit xxx if set, defines Title header value
wvl xxx if set, defines WaveLength header value
pro "Saxs"|"Waxs" projection type of image (default Saxs)
rot_1 angle (rad) for detector rotation plane 1> (default 0.)
rot_2 angle (rad) for detector rotation plane 2> (default 0.)
rot_3 angle (rad) for detector rotation plane 3> (default 0.)
base_name name(default "image")
verbose -1|0|1|2 message printing level (default 1)
simul 0|1 (default 0)
do_distortion 0|1|2|3 distortion correction (default 1) (0: none, 1: after dark, 2: after flat, 3: after norm)
flat_distortion 0|1 normalize to flat image (default 0)
norm_int 0|1 intensity normalization (default 0 = no)
norm_factor intensity normalization factor> (default 1.)
overflow= xxx (default 65535)
dummy value (default 0. = not set)
inp_min (default 0. = not set)
inp_max (default 0. = not set)
bin_1 factor for x-binning (default 1 = no binning)
bin_2 value factor for y-binning (default 1 = no binning)
azim_int 0|1 azimuthal integration (default 0 = no)
azim_pass 0|1 pass full header to azimuth. integr. (def. 1 = yes)
azim_id shared memory id of integrated image> (default -1)
azim_ext azimuth image file extension> (default none)
azim_r0 minimum integration radius (default 0.)
azim_r_num radial output size (default 0)
azim_a0 1st integration start angle (default 0.)
azim_a1 2nd integration start angle (default: not used)
azim_da angular integration interval (default 1.)
azim_a_num angular output size (default 0)
ave_id shared memory id of averaged image> (default -1)
ave_scf constant averaging scale factor> (default 1.)
mask_file azimuthal integration mask file name> (default: not used)
clear 0|1 reset all command options (default 0)

dvo Data value offset ; use it with type (see below). Available for linux64 bits only. SPDVERSION must be set to new.
type Values are : Unsigned16 or FloatIEEE32. Available for linux64 bits only. SPDVERSION must be set to new.

Options details

Many of these options are not used by the preprocessor. Those that are used are described in more detail here (the text below corresponds to the comments of the analyse_args() routine of spd) : The possible options are described below in alphabetical order.
active_radius defines a circular "active area" in the image. No spatial distortion corrections are done for pixels outside this area (default: 0., i.e. no "active area" used)
ave_id shared memory segment identifier for the azimuthal averaged output image (default: -1, i.e. no identifier specified)
ave_scf scale factor for the averaged values of the azimuthal image (default: 1.)
azim_a0 start angle for 1st azimuthal integration (default: 0.0)
azim_a1 start angle for 2nd azimuthal integration (default: not used)
azim_a_numangular dimension of output buffer for azimuthal integration(default: 0)
azim_da angle interval for azimuthal integration (default: 1.0)
azim_ext filename extension for the azimuthal integrated output image file (default: empty string, i.e. no output file written). The base of the filename is in "base_name"
azim_id shared memory segment identifier for the azimuthal integrated output image (default: -1, i.e. no identifier specified) The two options azim_ext and azim_id specify the output for the azimuthal integrated image. This can be: - azim_ext: a output image file; - azim_id: a shared memory segment. The default values are that no output for the azimuthal integrated image will be produced (no shared memory segment and no filename extension specified).
azim_int if set, integrate the image along the azimuth angle (default: 0, i.e. no integration)
azim_pass if set, all header values of the corrected image are passed to the azimuthal integrated image (default: 1, i.e. set)
azim_r0 minimum radius for azimuthal integration (default: 0.0)
azim_r_num radial dimension of output buffer for azimuthal integration (default: 0)
base_name contains the "file name base" from which all other file names are derived (default: "image")
bckg_const constant to be added to the value of all scattering background image pixels (default: 0.)
bckg_fact multiplication factor for the value of all scattering background image pixels (default: 1.)
bckg_const and bckg_fact are applied to the scattering background image as given in the following formula: scattering bckg_fact + bckg_const
bckg_file name of the file with the scattering background image (default: no file, i.e. NULL pointer)
bckg_id shared memory segment identifier for the scattering background image (default: -1, i.e. no identifier specified) The two options bckg_id and bckg_file specify the input source for the scattering background image. This can be: - bckg_id: a shared memory segment; - bckg_file: a scattering background image file. Default is no scattering background correction (no shared memory segment nor scattering background file defined). Note that only one scattering background image input source can be specified; if more than one is specified in the input arguments, then only the last one will be taken into account.
bin_1 number of pixels to bin together in x-direction (default: 1, i.e. no binning to be performed)
bin_2 number of pixels to bin together in y-direction (default: 1, i.e. no binning to be performed)
bis_1 if set, defines value for "BSize_1" header keyword.
bis_2 if set, defines value for "BSize_2" header keyword.
bkg_const old name of "dark_const" parameter (do not use)
bkg_file old name of "dark_file" parameter (do not use)
bkg_id old name of "dark_id" parameter (do not use)
cen_1 if set, defines value for "Center_1" header keyword.
cen_2 if set, defines value for "Center_2" header keyword.
clear reset all previously given options to their default values (default: 0, i.e. the previously given options are not reset)
cor_ext filename extension for the corrected output image file (default: empty string, i.e. no output file written). The base of the filename is in "base_name"
cor_file name of the output file for the corrected image (default: no file, i.e. NULL pointer). This option is obsolete and should be replaced by "cor_ext" with "base_name".
cor_id shared memory segment identifier for the corrected output image (default: -1, i.e. no identifier specified) The two options cor_id and cor_file specify the output for the corrected image. This can be: - cor_id: a shared memory segment; - cor_file: a output image file. Default is no output location (no shared memory segment nor output file defined).
dark_const: constant for overall dark image subtraction (default: 0.) For more details, see "dark_id" below.
dark_ext filename extension for the file with the dark (background) image. This is mainly used to save an online dark image to a file. (default: empty string, i.e. no output file written). The base of the filename is in "base_name"
dark_file name of the file with the dark image (default: no file, i.e. NULL pointer) If dark_file contains a string value with a leading and a trailing square bracket (e.g. dark_file = [char_string]), then the name of the dark image file is to be read from the keyword "char_string" in header of the source image file. Add option verbose = 2 to get dark file name while processing.
dark_id shared memory segment identifier for the dark image (default: -1, i.e. no identifier specified) The three options dark_const, dark_id and dark_file specify the input source for the dark image correction. This can be: - dark_id: a shared memory segment; - dark_file: a dark image file; - dark_const: an overall constant to be applied to all pixels of the image data. Default is no shared memory segment nor dark image file defined and the overall dark image constant 0. That also implies that by default there is no dark image correction performed. If a source for the dark image correction is specified, then normally the dark image correction is performed. However, this can be prevented by setting "do_dark = 0" (see below). Note that in principle only either a shared memory segment or an image file can be specified; if both are specified in the input arguments, then the one specified last will be used. The overall constant can be specified in addition to either of the two other options.
distortion_file name of the file with the distortion correction parameters (default: "spatial.dat"). Note: if "xfile" and "yfile" are specified, "distortion_file" is ignored.
dis if set, defines value for "SampleDistance" header keyword.
do_dark if set to 0, no dark image correction is performed, even if there is a source for it (dark image buffer, file or constant - see "dark_id", "dark_file" and "dark_const" above). The purpose of this is to allow a saving of the online dark image buffer for a later processing. If set to 1 (default), then the dark image correction is performed if there is a source for it.
do_distortion controls the distortion correction: 0: no distortion correction is performed >0: distortion correction is performed as follows: 1: after the dark image subtraction (default) 2: after the flatfield division 3: after the normalization.
dummy value that is used to ignore a pixel. Pixels with this value are not processed in the analysis (default: 0., i.e. not set)
flat_after flag indicating whether the floodfield correction is to be done before or after the distortion correction. If the flag is set, then floodfield will be done after distortion (default: 1, i.e. set). This is obsolete, use "do_distortion" instead.
flat_distortion if set, the target image is normalized to a flat image (default: 0, i.e. not set)
flood_file name of the file with the floodfield image (default: no file, i.e. NULL pointer)
flood_id shared memory segment identifier for the floodfield image (default: -1, i.e. no identifier specified) The two options flood_id and flood_file specify the input source for the floodfile image. This can be: - flood_id: a shared memory segment; - flood_file: a floodfile image file. Default is no floodfield correction (no shared memory segment nor floodfield file defined). Note that only one floodfield image input source can be specified; if more than one is specified in the input arguments, then only the last one will be taken into account.
from_ext filename extension for the input image file (default: ".edf")
header_ext filename extension for the file with the header of the input source image. This is mainly used to save the online header to a file when the input source image itself is not saved. (default: empty string, i.e. no header file written). The base of the filename is in "base_name"
header_id shared memory segment identifier where additional header information for the output image is available (default: -1, i.e. no identifier specified)
header_min set minimum header length for output files (default: 0, i.e. take default value from EDF routines)
i0 if set, defines value for "Intensity0" header keyword.
i1 if set, defines value for "Intensity1" header keyword.
inp_const constant to be added to the value of all source image pixels (default: 0.)
inp_exp exponent applied to the value of all source and dark image pixels (default: 1.)
inp_factor multiplication factor for the value of all source image pixels (default: 1.)
inp_const, inp_exp and inp_factor are applied to the source and dark image as given in the following formula: corrected = (source ^ inp_exp - dark ^ inp_exp) inp_factor + inp_const
inp_max maximum allowed value for a pixel. Pixels with bigger values are not processed in the analysis (default: 0., i.e. not set)
inp_min minimum allowed value for a pixel. Pixels with smaller values are not processed in the analysis (default: 0., i.e. not set)
mask_file name of the file with a mask image of pixels to ignore for azimuthal integration (default: no file, i.e. NULL pointer)
norm_factor multiplication factor for the value of all scattering intensity normalized image pixels (default: 1.). Used only if "norm_int" is set
norm_int if set, normalize image to absolute scattering intensities (default: 0, i.e. no normalization)
overflow pixel value used to mark an overflow (default: 0xffff)
off_1 if set, defines value for "Offset_1" header keyword.
off_2 if set, defines value for "Offset_2" header keyword.
ori if set, defines value for "RasterOrientation" header keyword.
pass if set, all header values of the input source file are read and written to the corrected output file (default: 0 not set)
pix_1 if set, defines value for "PSize_1" header keyword.
pix_2 if set, defines value for "PSize_2" header keyword.
pro string defining projection type to calculate the scattering vectors for the azimuthal integration (default: "Saxs"): "Saxs" normal SAXS images "Waxs" images that have been projected to the Ewald sphere
psize_distort if set, certain image parameters for the corrected image are taken from the distortion files (default: 0, i.e. not set). If psize_distort = 1, only the pixel size for the corrected image is taken from the distortion files. If psize_distort = 2, the pixel size, center, offset, sample distance, binning size, projection and rotation for the corrected image are taken from the distortion file. If psize_distort is set and any of the input arguments pix_1, pix_2, cen_1, cen_2, off_1, off_2, bis_1, bis_2, dis, pro, rot_1, rot_2 or rot_3, ori, wvl are set as well, then the value given in the input arguments has precedence over the value in the distortion files.
rot_1 angle (in radian) for the detector rotation in plane 1
rot_2 angle (in radian) for the detector rotation in plane 2
rot_3 angle (in radian) for the detector rotation in plane 3 (default: 0. for all 3 angles)
save_dark if set, the SPEC shared memory segment for the dark current ( = background) image is saved to a file with extension ".dark". Possible values: 0 = not set, 1 = save always, 2 = save if new image (default). Saving will only happen if the input source image is also saved (i.e. "src_ext" is not empty)
scat_const old name of "bckg_const" parameter (do not use)
scat_fact old name of "bckg_fact" parameter (do not use)
scat_file old name of "bckg_file" parameter (do not use)
scat_id old name of "bckg_id" parameter (do not use)
simul_id if set, the routine only produces a simulated grid with Gaussian peaks and puts it to the output destination; no image processing is done (default: 0, i.e. not set)
src_ext filename extension for the file with the input source image. This is mainly used to save an online input data to a file. (default: empty string, i.e. no output file written). The base of the filename is in "base_name"
src_id shared memory segment identifier for the input image data (default: -1, i.e. no identifier specified) Note that if there is both a shared memory segment and filename(s) specified for the input image data, only the filename(s) will be used.
tit if set, defines string value for "Title" header keyword.
to_ext filename extension for the corrected image file (default: ".cor"). This is obsolete, use "cor_ext" instead
verbose controls the level of message printing from the program: -1: nothing is printed; 0: print only the message with types ERROR or FATAL; 1: (default) print all messages except those of type DMSG (debug); 2: print all messages including debugging messages.
wvl if set, defines value for "WaveLength" header keyword.
xfile name of the input file with the values of the distortion corrections for the x coordinate (default: no file, i.e. NULL pointer). Needs to be specified simultaneously with "yfile". See also remark at "distortion_file" above.
xoutfile name of the output file for the values of the distortion corrections for the x coordinate (default: no file, i.e. NULL pointer)
yfile name of the input file with the values of the distortion corrections for the y coordinate (default: no file, i.e. NULL pointer). Needs to be specified simultaneously with "xfile". See also remark at "distortion_file" above.
youtfile name of the output file for the values of the distortion corrections for the y coordinate (default: no file, i.e. NULL pointer)
dvo and type These options are available for linux64 for instance. Use these options to write output file as float or as unsigned integer, and you need to export SPDVERSION=new. To write output files with 16-bit unsigned integers and to offset the data values by 10 the call is spd dvo=-10 type=Unsigned16 dark_file=gc14_0_0034bccddark gc14_0_0034bccdraw dvo must be added later to the stored data values to retrieve the correct values. The dvo value is written as an integer value after the header key DataValueOffset (default 0). The back-conversion is done automatically when the data are read by spd or one of the saxs-programs. Attention, DataValueOffset must always be added, independent of the data type. Currently, only Unsigned16 and FloatIEEE32 are available as type-values.