spd(1)

✨ NAME ✨

spd — the SPatial Distortion Program, aka your new bestie for X-ray image glow-ups 💅

🌸 SYNOPSIS 🌸

Synchrotron image corrections and azimuthal integration. That's it, that's the vibe. ✨

🦋 DESCRIPTION 🦋

okay so. SPD stands for SPatial Distortion. No cap. It's written in C, it's command-line driven, and it deals with images coming from X-ray diffusion/diffraction experiments. She's a real one.

Here's the pipeline, in order, and yes she does all of it:

• intensity corrections (dark current, flat field correction, ...),
• geometry corrections using spline files or a pair of distortion arrays,
• azimuthal integration in 2D or 1D after masking defective pixels.

SPD was originally written by Jorg Klora for ESRF and was re-written by Peter Boesecke from ESRF/ID02. Maintenance and packaging of the program are provided by Rainer Wilcke and Jerome Kieffer from SciSoft at ESRF. Shoutout to the devs, absolute icons. 👑

💅 OPTIONS 💅

Usage, copy it exactly bestie:

spd [--server] [--exit]  parameter=option [filenames]

Every single one of these, in order, no skipping, we are thorough in this house:

• src_id=<source image shared memory id> — the shared memory id where your source image lives.
• src_ext=<source image file extension> — file extension for the source image (default none).
• cor_id=<shared memory id of corrected image> — shared memory id of the corrected image.
• cor_ext=<corrected image file extension> — file extension for the corrected image (default none).
• type=<output data type> — the output data type (default "FloatIEEE32").
• dvo=<value> — data value offset (default 0).
• dark_id=<dark image shared memory id> — shared memory id of the dark image.
• dark_file=<dark image file name> — file name of the dark image.
• dark_const=<value> — subtract a constant dark image value. Default: no dark image subtraction done.
• dark_ext=<dark image file extension> — file extension for the dark image. 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. 0: never, 1: always, 2: only if new (default 2).
• inp_const=<value> — add input image constant (default 0.).
• inp_exp=<value> — apply exponent to input image (default 1.).
• inp_factor=<value> — multiply with input image factor (default 1.).
• raw_cmpr="none"|"gzip"|"z" — compression of raw & dark images (default none).
• flood_id=<flood field image shared memory id> — shared memory id of the flood field image (or flat field).
• flood_file=<flood field image file name> — file name of the flood field image (default: no flood field used).
• bckg_id=<scattering background image shared memory id> — shared memory id of the scattering background image.
• bckg_file=<scattering background image file name> — file name of the scattering background image (default: no scattering background used).
• bckg_const=<additive scattering constant> — additive scattering constant (default 0.).
• bckg_fact=<constant scattering factor> — constant scattering factor (default 1.).
• header_id=<shared memory id for data header> — shared memory id for the data header (default: not used).
• pass=0|1 — pass input file header to output (default 0).
• header_min=<minimum header length for output file> — minimum header length for the output file (default 0).
• header_ext=<extension for header output file> — extension for the header output file (default none).
• distortion_file=<file> — the distortion file (default "spatial.dat").
• xfile=<file> — x distortion read from an edf file.
• yfile=<file> — y distortion read from an edf file.
• xoutfile=<file> — x distortion saved to an edf file.
• youtfile=<file> — y distortion saved to an edf file.
• active_radius=<value> — values outside will not be corrected.
• precen_1=xxx — for pre-rotation center_1 (default calculated).
• precen_2=xxx — for pre-rotation center_2 (default calculated).
• predis=xxx — for pre-rotation distance (default calculated).
• prerot_1=<angle (rad) for pre-rotation around axis 1> — pre-rotation angle around axis 1 (default 0.).
• prerot_2=<angle (rad) for pre-rotation around axis 2> — pre-rotation angle around axis 2 (default 0.).
• prerot_3=<angle (rad) for pre-rotation around axis 3> — pre-rotation angle around axis 3 (default 0.).
• 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 the Center_1 header value.
• cen_2=xxx — if set, defines the Center_2 header value.
• i0=xxx — if set, defines the Intensity0 header value.
• i1=xxx — if set, defines the Intensity1 header value.
• off_1=xxx — if set, defines the Offset_1 header value.
• off_2=xxx — if set, defines the Offset_2 header value.
• pix_1=xxx — if set, defines the PSize_1 header value.
• pix_2=xxx — if set, defines the PSize_2 header value.
• bis_1=xxx — if set, defines the BSize_1 header value.
• bis_2=xxx — if set, defines the BSize_2 header value.
• dis=xxx — if set, defines the SampleDistance header value.
• ori=xxx — if set, defines the RasterOrientation header value.
• tit=xxx — if set, defines the Title header value.
• wvl=xxx — if set, defines the WaveLength header value.
• pro="Saxs"|"Waxs" — projection type of image (default Saxs).
• rot_1=<angle (rad) for detector rotation plane 1> — detector rotation plane 1 angle (default 0.).
• rot_2=<angle (rad) for detector rotation plane 2> — detector rotation plane 2 angle (default 0.).
• rot_3=<angle (rad) for detector rotation plane 3> — detector rotation plane 3 angle (default 0.).
• base_name=<name> — the base name (default "image").
• outdir=<pathname> — directory for output files (default: base_name).
• verbose=-1|0|1|2 — message printing level (low -> high, default 1).
• version=0|1 — print version string of the program if != 0.
• 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 imgage (default 1). and yes the manpage really does say "imgage", we stan a legend 🫶
• do_prerotation=0|1|2 — pre-rotation correction (default 1). (0: none, 1: after, 2: without distortion correction).
• norm_int=0|1 — intensity normalization (default 0 = no).
• norm_factor=<intensity normalization factor> — intensity normalization factor (default 1.).
• overflow=xxx — (default 0 = not set).
• dummy=<value> — (default 0. = not set).
• inp_min=<value> — (default 0. = not set).
• inp_max=<value> — (default 0. = not set).
• bin_1=<value> — factor for x-binning (default 1 = no binning).
• bin_2=<value> — factor for y-binning (default 1 = no binning).
• azim_int=0|1 — azimuthal regrouping (default 0 = no).
• azim_pass=0|1 — pass full header to azimuthal regrouping (def. 1 = yes).
• azim_pro="Saxs"|"Waxs" — project. type of azim. regrp. (default Saxs).
• azim_id=<shared memory id of regrouped image> — shared memory id of the regrouped image (default -1).
• azim_ext=<file extension of regrouped image> — file extension of the regrouped image (default none).
• azim_r0=<value> — minimum regrouping radius (default 0.).
• azim_r_num=<value> — radial output size (default 0).
• azim_a0=<degrees> — 1st regrouping start angle (default 0.).
• azim_a1=<degrees> — 2nd regrouping start angle (default: not used).
• azim_da=<degrees> — angular regrouping interval (default 1.).
• azim_a_num=<value> — angular output size (default 0).
• ave_id=<shared memory id of averaged image> — shared memory id of the averaged image (default -1).
• ave_ext=<file extension of averaged image> — file extension of the averaged image (default none).
• ave_scf=<scale factor for "s" values> — scale factor for "s" values (default 1.).
• mask_file=<azimuthal regrouping mask file name> — the mask file for azimuthal regrouping (default: not used).
• --server — switch to server mode, i.e. wait for new command/image to process on stdin. she's just gonna sit there and listen, patient queen 🌈
• --exit — quit the program when we are on server mode.

😭 BUGS 😭

okay so there are two things you NEED to know, and I'm saying them with my whole chest:

Azimuthal integration can only be achieved if a wavelength is given, even if it is not needed for any calculation. Like, even if the math doesn't care, the program does. Give her the wavelength. Periodt.

• SPD was developed at ESRF and is tightly bound to Spec shared-memory arrays (http://www.certif.com) and EDF (ESRF Data Format) images, both in input and output.

and that's the whole page bestie, you ate that 💖 this was spd(1) from the General Commands Manual, built as SPD=1.3 SAXS=2.445 EDF=2.188, dated Oct 5 2011 — a classic, an icon, no notes. mwah 🎀🦋✨