NAME#

imgcvt - image format conversion for Dectris CBF images and mar images into HDF5, TIFF, raw integer, Bruker sfrm, mrcfile

SYNOPSIS#

imgcvt [ -h (--help) ] [ -a (--add) N ] [ -c (--cfg) configuration file ] [ -C (--compressor) COMPRESSOR ] [ --data ] [ -o (--dir) OUTDIR ] [ -D (--deb=DEBUG) ] [ -g (--gui) ] [ --gz (--gzip) ] [ -i (--infile) file ] [ --blz4 ] [ --lzf ] [ --cbf ] [ --h5 ] [ --int16 ] [ --int32 ] [ --mrc ] [ --mrc1 ] [ --sfrm ] [ --tiff16 ] [ --tiff32 ] [ -S (--subdir) ] [ -f (--ffrm) FFRM ] [ -l (--lfrm) LFRM ] [ -k (--kfrm) KFRM ] [ -n (--nfrm) NFRM ] [ -F (--ff) ] [ -m (--master) ] [ -M (--pm) ] [ --mask FILE ] [ --raw [WxH][xBPP][+offset] ] [ -T (--tool) NAME ] [ -v (--verbose) ] [ -V (--VERSION) ] [ filename ]

DESCRIPTION#

imgcvt is a console program with optional graphical user interface for converting X-ray diffraction images into other formats (tiff, sfrm, hdf5, mar345, marccd, raw integer, mrc). Other than most other diffraction images, HDF5 files often consist of one or more data files that may contain a large number of actual diffraction images and a \"master\" file that carries information common to all data, typically the goniometer data and other parameters that describe the experiment. Also the mrc format common in electron microscopy as well as the tiff files may contain multiple images in one file. The program imgcvt currently supports the following input formats:

cbf (all sorts)
sfrm
tiff32 (32 bit data)
tiff16 (16 bit data)
mar345
mar300
marccd
int16
int32
h5\

OPTIONS#

-a (--add) N: Add N images up before writing into an output file.
-c (--cfg) FILE: FILE is a configuration file for specifying header information for output files, in particular for use with h5 and cbf files. See section CONFIGURATION FILE for details
-C (--compressor) COMPRESSOR: HDF5 output only: COMPRESSOR can be one of \"blz4\" (default), \"lzf\", \"gzip\" or \"None\". Data conversion without compression is much faster but the resulting hdf5-files will be about 50-90% larger than with \"blz4\" compression.
-D--deb=DEBUG: Hexadecimal debug code
--data: HDF5 output only: create data files, mo master file. By default, the program produces both data and master files.
-F (--ff): HDF5 input only: when given, a flatfield mask will be extracted from the input master file - if it exists - and written out as TIFF file. The name of the output file will be {rootname}_flatfield.bin
-g, (--gui): Start the program with a graphical user interface. The GUI allows for loading images and also modifying header values. If no input file is given, the program automatically start in GUI mode.
--gz --gzip: HDF5 output only: use gzip compression instead of blz4.
-i (--infile) FILE: Optional input file parameter. The input file should have the general form prefix_###.suffix, where ### (or more #) is a running image number. You may either use the hashtag character or an actual numeric value. Either way, the program converts the string into a template.
-h (--help): Prints a summary of program command line options.
--cbf: Use cbf as output format.
--int16: Use 16-bit integers as output format without header.
--int32: Use 32-bit integers as output format without header.
--mrc: Write all data of the series into a single file in MRC format. Data are stored as 16-bit unsigned integers with all values exceeding 16-bits set to 0.
--mrc1: For each input file, write a separate file in MRC format, i.e. the output images only contain data from a single image.
--sfrm: Use Bruker sfrm as output format for use with APEX4.
--tiff16: Use 16-bit TIFF as output format.
--tiff32: Use 32-bit TIFF as output format.
-T (--tool) NAME: Use tool NAME in computations
-f (--ffrm) FFRM: Starting frame of series.
-l (--lfrm) LFRM: Ending frame of series.
-k (--kfrm) KFRM: When creating output images, start numbering with KFRM. By default, the numbers of input files will be used.
-n (--nfrm) NFRM: HDF5 output only: put up to NFRM images into each hdf5 data file.
-m (--master): HDF5 output only: when given, no data files will be produced but only a master file.
-M (--pm): HDF5 input only: when given, a bad pixel mask will be extracted from the input master file - if it exists - and written out as TIFF file. The name of the output file will be {rootname}_mask.tif
--mask: HDF5 output only: when given, no data files will be produced but only a master file.
-o (--dir) OUTDIR: The o/p=files will be written to OUTDIR when given. Otherwise, depending on the chosen output format a subdirectory \"tiff16\", \"tiff32\", \"sfrm\", \"int16\", \"int32\" or \"h5\" will be used. If the subdirectory does not exist, it will be created.
--raw=WxH[xBPP][+OFFSET]: When processing raw images, the program needs to know the pixels in x (W) and y (H) and the bytes per pixel (BPP, defaults to 4). If the images have headers with a fixed length, you need to provide the corresponding number of bytes as OFFSET.
-S (--subdir): If specified, output files will be written in a subdirectory of the directory where the input file comes from. The name of the subdirectory depends on the output format. E.g.: if \"sfrm\" is the output format, a subdirectory sfrm will be created.
-T (--tool) NAME: The program can also be used for special purposes by calling tools. Currently, the following tools are implemented:

mask - Creates a bad pixelmask. This expects a h5 master file as input and a couple of tens to hundreds of empty image data. The tools writes a bad pixel mask into a tif file called {rootname}_mask.tif that contains bad pixels marked with value 16, good pixels are 0.
direct[:N] - Computes the direct beam coordinagtes from a series of images. The optional parameter N specifies the search radius around the center coordinates as given in the input file. Default for N is 8 pixels. See section DIRECT BEAM for more details
bkg - Computes a background table from a series of images. When working with single crystal diffraction images This works better the more images are contained within the series in order to remove diffraction spots. The resulting background table is written out in TIFF format.
peaks - Extract diffraction spots from an image or a series of images. The diffraction spots are written out as ASCII file into a file with extension .pks that can be read by marIndex or other crystal indexing programs. It contains spot coordinates, spot size, I/Sigma and number of pixels contributing to the spot.

-v (--verbose): Increases verbosity level for more program output.
-V (--VERSION): Only show program version and exit.
filename: Any argument not given with any of the keywords above will be treated as input file argument.

GUI#

The graphical user interface should be self-explaining. Afer loading an initial image, the header information is extracted and entered into the corresponding fields. If you edit any of the header fields, modified values will change the color. The values given here will end up in the HDF5-headers unless they are overwritten by program initialization file (see below). Please note, that the distance shown in the header file is given in mm for sake of clarity. In the HDF5, the distance usually is given in meters. The conversion will be done automatically.

DIRECT BEAM#

The ELDICO electron diffractometer does not have a beam stop, so the direct beam is visible in diffraction images unless the beam hits solid parts of the sample holder. The direct beam is the most accurate value for the origin of diffraction, a parameter that is very important to be accurate in most data processing programs. It is especially important to rely on it because in small molecule sample there may not be sufficient reflections to refine the center coordinates from. When using tool \"direct\", the conversion program takes the center coordinates of the input file and looks in a radius of N pixels (N=8 by default) for pixel values > 10000. For all selected pixels in a rectangular area of NxN pixels around that given center, a center of gravity is computed. When processing a series of images, in a first round only the average center of all input images is computed and then applied to the converted images in a second round. The search radius N can be modified by adding argument :N to \"direct\" like in \"direct:10\".

INPUT FILES#

The program automatically determines wether a selected file is an implemented image format and loads the file accordingly. The following image formats are implemented:

cbf:: Images in \"CBF\" format or miniCBF format (DECTRIS).
mar345:: Images in mar345 format. Usual extensions: .marXXXX where XXXX is 1200, 1600, 1800, 2000, 2300, 2400, 2560, 1536, 3000, 3072 or 3450
marCCD:: Images in marCCD format. No standard extension
h5:: hdf5 files as produced by Dectris detectors (master and data files)
sfrm:: Bruker sfrm formatted images
tiff:: TIFF files (8, 16, 32-bit integers, also floats)
mrc:: MRC files with one or more images.

OUTPUT FILES#

When using HDF5 output, the program produces both master and data files by default. The master file has no actual image data but only information describing the experiment. The data files can be a single file containing thousands of diffraction images. If you like, you may also produce an data file for each single input file, which is less efficient. This can be done by providing the input option \"-nfrm\" on the command line or by setting the value for \"# images/h5\" in the GUI. By default, all images found in a directory will go into one data file.

TIFF output comes in 2 flavours:

16-bit data (tiff16)
32-bit data (tiff32)

When using tiff16, input data are truncated to 16-bits (65535). The file contains a plain array of x*y 16 bit data. When using tiff32, x*y 32-bit values are written into the file.

When using raw image output, a plain array of x*y 16-bit (int16) or 32-bit (int32) data is generated. The output file comes without header.

When using sfrm output (default), images are written in Bruker 100 format.

When using mrc, input data are truncated to 16-bits (65535). The file contains a plain array of x*y 16 bit data. One mrc file may contain multiple images. A mrc-file containing multiple images can be used as input file. It will produce as many output files as there are entries in the file.

CONFIGURATION FILE#

The program reads a Windows type configuration file from the following locations (in the order of precedence):

./imgcvt.cfg
\$HOME/.imgcvt.cfg
\$HOME/.mar.cfg
/usr/local/mar/imgcvt.cfg

Following the convention of .ini-files on Windows, the program reads configuration values from the section starting with line:

[imgcvt]

All further entries given here will go into the output master file and values read from input image headers or those given in the GUI will be ignored! Therefore, you should only provide parameters in the configuration file that you would consider to be static. While you are allowed to give goniometer parameters like \"phi\", it is not recommended to do that here. Please see the section COMPLETE EXAMPLE, but refrain from using the goniometer parameters.

COMPLETE EXAMPLE for imgcvt.cfg#

[imgcvt]
wavelength=1.3477
detector_distance=120.0
bit_depth_readout=16
element="Cu"
wavelength=1.541789
beam_center_x=1150.0
beam_center_y=1150.0
frame_period=10.0
frame_time=10.0
bit_depth_readout=32
sensor_material="Silicon"
description="None"
detector_number="000-000"
sensor_thickness=0.00450
threshold_energy=4000
detector_distance=120.0
two_theta=0.0
two_theta_start=0.0
two_theta_end=0.0
two_theta_increment=0.0
two_theta_range_total=0.0
two_theta_range_average=0.0
kappa=0.0
kappa_start=0.0
kappa_end=0.0
kappa_increment=0.0
kappa_range_total=0.0
kappa_range_average=g
omega=0.0
omega_start=0.0
omega_end=0.0
omega_increment=0.0
omega_range_total=0.0
omega_range_average=0.0
chi=0.0
chi_start=0.0
chi_end=0.0
chi_increment=0.0
chi_range_total=0.0
chi_range_average=0.0
phi=0.0
phi_start=0.0
phi_end=0.0
phi_increment=0.0
phi_range_total=0.0
phi_range_average=0.0

AUTHOR#

Claudio Klein, Marxperts GmbH, Norderstedt, Germany

COPYRIGHT#

ADDRESS#

_

Marxperts GmbH Phone: +49 - (40) - 529 884-0 Werkstr. 3 FAX: +49 - (40) - 529 884-20 D-22844 Norderstedt - GERMANY info\@marxperts.com www.marxperts.com _