Previous: hints: List or modify "collect" global variables
Next: imagebin: Construct 2x2 binned image from unbinned

imagesum: add/subtract images

The "imagesum" program can manipulate and combine images.

Usage

The program is invoked by the command line:

  imagesum <imagefilenames and options> [write=imagefilename]

Different image file types are recognized from their names.

The program starts by reading the first filename and, depending on the selected "operation" (see below), it adds or subtracts it from the zeroed buffer image. Subsequent files are then processed according to the operation selected for them.

The outputfile produced by the program contains the final data from the buffer. The header of the output file is a proper sum of all image headers if all images were added together and were either all identical scans, or all consecutive scans. In other cases it will be the header of the last file that was read. The output file always consists of a single frame without repeats.

Operations

Different operations between images are supported:

add: add image to buffer
sub: subtract image from buffer
div: divide buffer by image
mul: multiply buffer by image
min: take pixel-wise minimum of buffer and image
max: take pixel-wise maximum of buffer and image
each: The odd one out: write an image for each image that is read, do not perform any operations between images.

The default operation is "add".

Other options

The program accepts the options to determine KCD file writing. The default output file name is sum.kcd

The option "newext=XXXX" specifies the extension that should replace the input extension. This is useful in combination with the "each" option to enable conversion of the images to another format.

The option "longdark" enables a correction for warm pixels based on a long shutter closed exposure. "nolongdark" switches it back off. This needs a "dark.kcd" or "dark.kcd_frozen" file in the current directory or in the calibration directory for the appropriate detector (see the inside information about dark images).

The option "shortdark" enables a correction for non-empty pixels. "noshortdark" switches it back off. This needs a "sdark.kcd_frozen" file in the current directory or in the calibration directory for the appropriate detector (see the inside information about dark images).

The option "localdark" enables a correction for warm and non-empty pixels based on a local "drk.kcd" image with the same scan name as the image (i.e. it will look for s01fdrk.kcd if you are reading s01f001.kcd). "nolocaldark" switches it back off.

The option "badpixel" enables a correction for unreliable pixels that can be replaced by a weighted average of their neighbours when they are outside of peaks. "nobadpixel" switches this filter back off.

The option "adc0" subtracts the ADC offset and a uniform dark current from each image before the operation. This is the default. "noadc0" switches this back off. The ADC offset is calculated from the image. For 65mm and 95mm KappaCCD detectors this can be done from some external pixels reserved for this purpose. As alternative, the "imagesum" program accepts an option "adc0=###", which implies "adc0" but fixes the adc offset to the given (floating point) value. Using "adc0=none" the default behaviour can be restored.

The options "dark" and "nodark" are a convenient abbreviation for "longdark shortdark adc0" and its "no"-equivalent.

The option "area" divides each pixel value by the relative pixel area. "noarea" switches this back off.

The option "ripplefilter" uses a 1D-FFT to remove ripples caused by LF interference from the image. "noripplefilter" switches this back off.

The option "slopefilter" removes the horizontal and vertical slope from the image. "noslopefilter" switches this back off.

The option "sensitivity" corrects for pixel sensitivity. "nosensitivity" switches this back off. This needs a sensitivity file for your detector either in the current directory or in the calibration directory for the appropriate detector.

The option "incidence" corrects for the angle of incidence on the detector "noincidence" switches this back off. For the best results this needs a proper detector alignment for your detector either in the current directory or in the calibration directory for the appropriate detector.

With the option "undistorted" the program will write a file that is corrected for pixel distortion. "distorted" switches this back off. This needs a file called fries.frs either in the current directory or in the calibration directory for the appropriate detector; see makefries on how to create this file. Please note that once an image is undistorted, it is very difficult to correct it for other effects later. It is therefore to be advised that undistortion is combined with all other desired corrections in one run of the imagesum program.

The option "correctall" is equivalent to "adc0 dark badpixel sensitivity incidence undistorted", all filters required for a complete correction of normal diffraction images.

The option "twoframe" asks the program to write a two-frame output image file. Normally the output file is a single dezingered frame, but some programs that read KCD image files require two frame files. Use this option if you need to read the resulting image in such a program. Use the "oneframe" option to counteract this.

Examples

imagesum i01*.kcd to isum.kcd

Adds all images i01*.kcd and write the result to isum.kcd

imagesum s01f001.kcd mul /usr/local/hklint/9602/sensi9602.kcd to xs01f001.kcd

Corrects the s01f001.kcd image for detector response.

imagesum min i01*.kcd to background.kcd

Creates a pseudo background-radiation image by taking the minimum of a series of images (but see backgroundimage for a slower but better alternative).

As followup to the previous example:

imagesum sub background.kcd add i01f001.kcd to xi01f001.kcd

Correct the first image in the series for background radiation. This is done in this order to preserve the header of the i01f001.kcd file in the output file.

Another followup, in the form of a shell script:

#!/bin/sh
mkdir bgcorr
for serie in 01 02 03; do
  backgroundimage n 3 s${serie}f*[05].kcd* to s${serie}fback.kcd
  for file in s${serie}f[0-9]*.kcd*; do
     /usr/local/nonius/bin/imagesum flatdark scale=0.5 shift=50 sub s${serie}fback.kcd add $file to bgcorr/$file
  done
done

This script creates for each of the series s01f* s02f* and s03f* a background image using every 5th image, and continues by correcting all kcd files in these series for the calculated background. The corrected dataset can be found in the subdirectory "bgcorr". The "scale=0.5 shift=50" arguments make sure that the resulting images should be readable by denzo, and that no overflows are created by adding image pairs (as done by the "dezingering" procedure).

mkdir darkcorr
foreach f (s*.kcd)
  imagesum dark scale=0.5 shift=50 $f to darkcorr/$f
end

Corrects a complete dataset for dark current (dezingering each of the images on the fly). The "scale=0.5 shift=50" arguments are needed if you want to use the resulting images in "denzo".

mkdir undistorted
imagesum writeprefix=undistorted/ each dark badpixel sensitivity incidence undistorted *.kcd

Corrects a complete dataset for all effects that normally are corrected during data processing, and then undistorts each of the images. Please note the trailing "/" on the writeprefix option: the prefix is literally positioned in front of the existing file name! The "each" option makes it possible to process a whole dataset in one run. The order in which the corrections are given is not important, but it is vital that the input files are specified after all of the correction options.

Previous: hints: List or modify "collect" global variables
Next: imagebin: Construct 2x2 binned image from unbinned