SECTION 3.2 - IMAGE BACKGROUND CALCULATION ROUTINES
3.2.1 INTRODUCTION
These are a set of routines for calculating a background image and background values from a single crystal X-ray diffraction image. The routines are written in C. Fortran interfaces are provided. They were written, in particular, for use with programs using XDL_VIEW routines, in particular xdl_image (xdlf_image) and related routines.The following sets of routines are available:
Background Calculation Routines
3.2.2 BACKGROUND CALCULATION ROUTINES
3.2.2.1 Introduction
The following routines are available:
Calculate background image using a 2-D search - xdl_bg_calc
Background 2-D search with progress bar - xdl_bg_calc_prog
Calculate radially averaged background - xdl_bg_strip
Form radially averaged background image - xdl_bg_radimg
Get background value from background function - xdl_bg_val
Get background value from background image - xdl_bg_valimg
3.2.2.2 Calculate background image using a 2-D search - xdl_bg_calc
The routine xdl_bg_calc (xdlf_bg_calc) is used to calculate a background image from an image. This is for single crystal X-ray diffraction images (i.e. one with spots over a fairly slowly changing background). The method calculates the background at a pixel by taking the average of the lowest pixel values in a box surrounding the pixel such that the number of such values is a requested percentage of the total number of pixels in the box. To optimise the calculation, the box is walked through the image moving a pixel at a time starting at the top left. It then repeats the process of left from to right, then one pixel down, then from right to left, and then one pixel down etc. until the film image has been covered. (In this description the slow moving image index is visualised as being from top to bottom and the fast one from left to right). The routines will cope with a maximum background level up to around 65000.
Fortran call:
CALL XDLF_BG_CALC (IMG, ITYPE, NSRASTS, NFRASTS, NFOFF,
+ NCMP, NPBOX, IPCNT, IMG_BG, NFBGOFF, IERR)
Parameters:
IMG (R) Array holding the image data
(normally packed into an integer array)
(see 'img')
ITYPE (R) Image data type =1 unsigned byte,
=2 unsigned two-byte,
=3 signed integer
=4 squashed i2
(see 'type')
NSRASTS (R) No. rasters along slow image axis
(see 'ns_rasts')
NFRASTS (R) No. rasters along fast image axis
(see 'nf_rasts')
NFOFF (R) Offset (in pixels) between successive slow
rasters (see 'nf_off')
NCMP (R) Compress (sample) NCMP into 1 pixel in each
direction for background image (see ncmp)
NPBOX (R) Dimension of background calculation box in
pixels of compressed imagee (preferably odd)
(see 'npbox')
IPCNT (R) Percentage of pixels to treat as background.
If -IPCNT is given, then pixel values of zero
will be omitted from the calculation.
(see 'percent')
IMG_BG (W) Array to hold the returned background image.
(pass an integer array large enough to hold
the returned image data) (see 'img_bg')
NFBGOFF (R/W) Offset between start of lines in returned
background image (allows for padding if
required). If zero on input then value will
be returned for no padding cases (see nf_bgoff)
IERR (W) Returns the status from the xdl_bg_calc
call
'C' call:
int xdl_bg_calc (img, type, ns_rasts, nf_rasts, nf_off, ncmp, npbox,
percent, img_bg, nf_bgoff)
Parameters:
char *img; /* Image from which to calculate the background
image (R)*/
int type; /* Image (and backgound image) data type
=1 unsigned byte
=2 unsigned two-byte data
=3 signed integer data
=4 'squashed i2' data (if Intensity>32767
store as 65536-Intensity/8)
(R)*/
int ns_rasts; /* No. of slow moving rasters in the image (R)*/
int nf_rasts; /* No. of fast moving rasters in the image (R)*/
int nf_off; /* Offset in the image (in pixels) between start
of each line of the image as stored (allows
for padding at the end of each line if
used) (R)*/
int ncmp; /* No. of pixels to compress into 1 in each
direction for the background image. The
size of the background image will be
ns_rasts/ncmp * nf_rasts/ncmp (integer
divisions) (R)*/
int npbox; /* Size of box (after compression of the image)
for each background calculation
in pixels (box is npbox*npbox) - preferably
an odd number (R)*/
int percent; /* Percentage of pixels to treat as background
If -percent is given, then pixel values of
zero will be omitted from the calculation
(R)*/
char *img_bg; /* Returns background image in same data format
as the input image. The size of the
background image will be
ns_rasts/ncmp * nf_rasts/ncmp (integer
divisions) (see also mf_bgoff) (W)*/
int *nf_bgoff; /* Offset between start of image lines in
returned background image. If value
given is less than nf_rasts/ncmp then
it will be reset to nf_rasts/ncmp (R/W)*/
Return: =0 OK; =1 background too high (> 65000); =2 box too big for image
3.2.2.3 Background 2-D search with progress bar - xdl_bg_calc_prog
The routine xdl_bg_calc_ptrog (xdlf_bg_calc_prog) is the same as xdl_bg_calc (xdlf_bg_calc) except that it has allows for routines to be passed to it to monitor the progress of the background calculation and to cancel i the calculation if required.
Fortran call:
CALL XDLF_BG_CALC_PROG (IMG, ITYPE, NSRASTS, NFRASTS, NFOFF,
+ NCMP, NPBOX, IPCNT, IMG_BG, NFBGOFF,
+ PROGRESS, CANCEL, IERR)
Parameters:
IMG (R) Array holding the image data
(normally packed into an integer array)
(see 'img')
ITYPE (R) Image data type =1 unsigned byte,
=2 unsigned two-byte,
=3 signed integer
=4 squashed i2
(see 'type')
NSRASTS (R) No. rasters along slow image axis
(see 'ns_rasts')
NFRASTS (R) No. rasters along fast image axis
(see 'nf_rasts')
NFOFF (R) Offset (in pixels) between successive slow
rasters (see 'nf_off')
NCMP (R) Compress (sample) NCMP into 1 pixel in each
direction for background image (see ncmp)
NPBOX (R) Dimension of background calculation box in
pixels of compressed imagee (preferably odd)
(see 'npbox')
IPCNT (R) Percentage of pixels to treat as background.
If -IPCNT is given, then pixel values of zero
will be omitted from the calculation.
(see 'percent')
IMG_BG (W) Array to hold the returned background image.
(pass an integer array large enough to hold
the returned image data) (see 'img_bg')
NFBGOFF (R/W) Offset between start of lines in returned
background image (allows for padding if
required). If zero on input then value will
be returned for no padding cases (see nf_bgoff)
PROGRESS (R) Subroutine to monitor progress. Will be
called after each processing 'strip'
as follows:
as follows:
CALL PROGRESS (IFLAG, NSTRIP, ISTRIP)
CALL PROGRESS (IFLAG, NSTRIP, ISTRIP)
IFLAG (R) =0 start, =1 in progress,
=2 done
NSTRIP (R) Total no. of strips of image to
process
ISTRIP (R) Current strip (1 to NSTRIP)
ISTRIP (R) Current strip (1 to NSTRIP)
CANCEL (R) This routine will be called at intervals to
see if a cancel state has been set.
see if a cancel state has been set.
The call is:
The call is:
CALL CANCEL (ICANCL)
CALL CANCEL (ICANCL)
ICANCL (W) Return 0 to continue, 1 to cancel
ICANCL (W) Return 0 to continue, 1 to cancel
IERR (W) Returns the status from the xdl_bg_calc_prog
call
'C' call:
int xdl_bg_calc_prog (img, type, ns_rasts, nf_rasts, nf_off, ncmp, npbox,
percent, img_bg, nf_bgoff, progress, cancel)
Parameters:
char *img; /* Image from which to calculate the background
image (R)*/
int type; /* Image (and backgound image) data type
=1 unsigned byte
=2 unsigned two-byte data
=3 signed integer data
=4 'squashed i2' data (if Intensity>32767
store as 65536-Intensity/8)
(R)*/
int ns_rasts; /* No. of slow moving rasters in the image (R)*/
int nf_rasts; /* No. of fast moving rasters in the image (R)*/
int nf_off; /* Offset in the image (in pixels) between start
of each line of the image as stored (allows
for padding at the end of each line if
used) (R)*/
int ncmp; /* No. of pixels to compress into 1 in each
direction for the background image. The
size of the background image will be
ns_rasts/ncmp * nf_rasts/ncmp (integer
divisions) (R)*/
int npbox; /* Size of box (after compression of the image)
for each background calculation
in pixels (box is npbox*npbox) - preferably
an odd number (R)*/
int percent; /* Percentage of pixels to treat as background
If -percent is given, then pixel values of
zero will be omitted from the calculation
(R)*/
char *img_bg; /* Returns background image in same data format
as the input image. The size of the
background image will be
ns_rasts/ncmp * nf_rasts/ncmp (integer
divisions) (see also mf_bgoff) (W)*/
int *nf_bgoff; /* Offset between start of image lines in
returned background image. If value
given is less than nf_rasts/ncmp then
it will be reset to nf_rasts/ncmp (R/W)*/
void (*progress)(); /* Function passed to the routine to monitor
the progress of the background calculation.
called as follows:
progress (iflag, nstrip, istrip);
int *iflag; =0 start, =1 in progress,
=2 done
int *nstrip; Total no. of strips of image to
process
int *istrip; Current strip (1 to nstrip)
(May be a NULL)
(R)*/
void (*cancel)(); /* Function passed to the routine to enable
cancellation. Called as follows:
cancel (icancl);
int *icancl; Function must return 0 to
continue, or 1 to cancel.
(May be a NULL)
(R)*/
Return: =0 OK; =1 background too high (> 65000); =2 box too big for image
-1 interrupted
3.2.2.4 Calculate radially averaged background - xdl_bg_strip
The routine xdl_bg_strip (xdlf_bg_strip) is used to calculate a radially averaged background from an image. The method calculates the background at a pixel by taking the average of the lowest pixel values in a box surrounding the pixel such that the number of such values is a requested percentage of the total number of pixels in the box. The background values are found for a horizontal (fast axis) or vertical (slow axis) strip of pixels running through the centre of the image and the values from the two halves of the strip are averaged. The routine will only cope with background levels up to around 65000.
Fortran call:
CALL XDLF_BG_STRIP (IMG, ITYPE, NSRASTS, NFRASTS, NFOFF, NCMP,
+ NPBOX, IPCNT, IOPT, IBGAVE, NBG, IERR)
Parameters:
IMG (R) Array holding the image data .
(normally packed into an integer array)
(see 'img')
ITYPE (R) Image data type 1 = unsigned byte, 2 =
unsigned two-byte, 3 = signed integer,
4 = 'squashed i2' (see 'type')
NSRASTS (R) No. rasters in slow image direction
(see 'ns_rasts')
NFRASTS (R) No. rasters in fast image direction
(see 'nf_rasts')
NFOFF (R) Offset (in pixels) between successive slow
rasters (see 'nf_off')
NCMP (R) Compress NCMP into 1 pixel in each direction
for background image (actually sample)
(see ncmp)
NPBOX (R) Dimension of background calculation box in
pixels of compressed image (preferably odd)
(see 'npbox')
IPCNT (R) Percentage of pixels to treat as background
(see 'percent')
IOPT (R) =1 strip across the centre along fast axis
=2 strip through the centre along slow axis
IBGAVE (W) Array returning radially averaged background
values (see bgave)
NBG (W) The number of values returned in IBGAVE
(maxr_off+1, see maxr_off)
IERR (W) Returns the status from the xdl_bg_strip
call
'C' call:
int xdl_bg_strip (img, type, ns_rasts, nf_rasts, nf_off, ncmp, npbox,
percent, iopt, bgave, maxr_off)
Parameters:
char *img; /* Full image data (R) */
int type; /* Data type =1 unsigned byte data
=2 unsigned two-byte data
=3 signed integer data
=4 'squashed i2' data
(R)*/
int ns_rasts; /* No. of slow rasters in image (R) */
int nf_rasts; /* No. of fast rasters in image (R) */
int nf_off; /* Offset in rasters between lines of
stored image (allows for padding) (R)*/
int ncmp; /* Compress ncmp pixels in each direction
into 1 before calculating background
(data are actually sampled) (R)*/
int npbox; /* Size of box for each background calculation
in pixels (box is npbox*npbox) - preferably
an odd number (box is for compressed
image) (R)*/
int percent; /* Percentage of pixels to treat as background
(R)*/
int iopt; /* =1, strip through centre along fast axis
=2, strip through centre along slow axis
(R)*/
int bgave[]; /* Returns radially averaged background function
in intervals of pixels of the compressed
image and starting from the centre of that
image; dimension to >= (nf_rasts/ncmp)/2
for iopt 1 and (ns_rasts/ncmp)/2 for iopt 2
(W)*/
int *maxr_off; /* Maximum offset in returned 'bgave' array
(W)*/
Return: =0 OK;
=1 Background too high (>65000)
=2 box too big for image
=3 Unable to allocate memory for temporary arrays;
3.2.2.5 Form radially averaged background image - xdl_bg_radimg
The routine xdl_bg_radimg (xdlf_bg_radimg) is used to form a a radially averaged background image from the radially averaged background function returned by xdl_bg_strip (xdlf_bg_strip).
Fortran call:
CALL XDLF_BG_RADIMG (ITYPE, NS_BG, NF_BG, NF_BGOFF, IBGAVE,
+ NBG, IMG_BG, IERR)
Parameters:
ITYPE (R) Required data type for background image
=1 unsigned byte
=2 unsigned two-byte
=3 signed integer
=4 'squashed i2'
(see type)
NS_BG (R) No. of rasters in background image along
slow moving axis (see ns_bg)
NF_BG (R) No. of rasters in background image along
fast moving axis (see nf_bg)
NF_BGOFF (R) Offset required between successive lines of
returned image (allows for padding if required)
(see nf_bgoff)
IBGAVE (R) Array with radially averaged background
values (see bgave)
NBG (W) The number of values in IBGAVE
(maxr_off+1, see maxr_off)
IMG_BG (W) Integer array returning background image
(must be large enough to hold
NS_BG*NF_BGOFF data pixels) (see img_bg)
IERR (W) Returns the status from the xdl_bg_radimg
call
'C' call:
int xdl_bg_radimg (type, ns_bg, nf_bg, nf_bgoff, bgave, maxr_off,
img_bg)
Parameters:
int type; /* Background image data type
=1 unsigned byte
=2 unsigned two-byte
=3 signed integer
=4 'squashed i2'
(R) */
int ns_bg; /* No. rasters in backgound image along slow
moving axis (R) */
int nf_bg; /* No. rasters in backgound image along fast
moving axis (R) */
int nf_bgoff; /* Required offset between successive lines of
returned background image (allows for padding
if required) (R) */
int bgave[]; /* Radially average background values from
xdl_bg_strip (R)*/
int maxr_off; /* Maximum offset in 'bgave' from xdl_bg_strip
(R)*/
char *img_bg; /* Returns the compressed radially averaged
background image (ns_bg*nf_bg padded if
required) (W)*/
Return: =0 OK;
3.2.2.6 Get background value from background function - xdl_bg_val
The routine xdl_bg_val (xdlf_bg_val) is used to get a background value at a given pixel position in the full image from a radially averaged background function as returned by xdl_bg_strip (xdlf_bg_strip). If the pixel is outside the range of the background function the value at the maximum available radius will be returned.
Fortran call:
CALL XDLF_BG_VAL (ISLOW, IFAST, IBGAVE, NBG, NSRASTS, NFRASTS,
NCMP, IVAL, IERR)
Parameters:
ISLOW (R) Pixel position along slow axis in full image
(from 1 up)
IFAST (R) Pixel position along fast axis in full image
(from 1 up)
IBGAVE (R) Array with radially averaged background
values (see bgave)
NBG (R) The number of values in IBGAVE
(maxr_off+1, see maxr_off)
NSRASTS (R) No. rasters along slow axis in full image from
which the background was calculated
NFRASTS (R) No. rasters along fast axis in full image from
which the background was calculated
NCMP (R) No. pixels in each direction compressed into
1 for the background calculation.
IVAL (W) Returned background value (see ival)
IERR (W) Returns the status from the xdl_bg_val
call
'C' call:
int xdl_bg_val (islow, ifast, bgave, maxr_off, ns_rasts, nf_rasts,
ncmp, ival)
Parameters:
int islow; /* The pixel position in the full image
along the slow axis (from 1 up) (R)*/
int ifast; /* The pixel position in the full image
along the fast axis (from 1 up) (R)*/
int bgave[]; /* Radially average background values from
xdl_bg_strip (R)*/
int maxr_off; /* Maximum offset in 'bgave' from xdl_bg_strip
(R)*/
int ns_rasts; /* No. of rasters along the slow axis of the image
used to calculate background function (R)*/
int nf_rasts; /* No. of rasters along the fast axis of the image
used to calculate background function (R)*/
int ncmp; /* No. of pixels in each direction compressed into
1 for the background calcn. (R)*/
int *ival; /* Returns background value (W)*/
Return: =0 OK;
3.2.2.7 Get background value from background image - xdl_bg_valimg
The routine xdl_bg_valimg (xdlf_bg_valimg) is used to get a background value at a given pixel position in the full image from a previously calculated background image (e.g. from xdl_bg_radimg (xdlf_bg_radimg) or xdl_bg_calc (xdlf_bg_calc)). If the pixel is outside the range of the background image the background value at the edge will be returned.
Fortran call:
CALL XDLF_BG_VALIMG (ISLOW, IFAST, IMG_BG, ITYPE, NF_BGOFF,
+ NCMP, IVAL, IERR)
Parameters:
ISLOW (R) Pixel position along slow axis in full image
(from 1 up)
IFAST (R) Pixel position along fast axis in full image
(from 1 up)
IMG_BG (R) Background image (e.g. from xdl_bg_calc
or xdl_bg_radimg (see img_bg)
ITYPE (R) Data type for background image
=1 unsigned byte
=2 unsigned two-byte
=3 signed integer
=4 'squashed i2'
(see type)
NF_BGOFF (R) Offset between successive lines of background
image (allowing for padding if used)
(see nf_bgoff)
NCMP (R) No. pixels in each direction compressed into
1 for the background calculation.
IVAL (W) Returned background value (see ival)
IERR (W) Returns the status from the xdl_bg_valimg
call
'C' call:
int xdl_bg_valimg (islow, ifast, img_bg, type, nf_bgoff,
ncmp, ival)
Parameters:
int islow; /* The pixel position in the full image
along the slow axis (from 1 up) (R)*/
int ifast; /* The pixel position in the full image
along the fast axis (from 1 up) (R)*/
char *img_bg; /* Background image (R)*/
int type; /* Background image data type
=1 unsigned byte
=2 unsigned two-byte
=3 signed integer
=4 'squashed i2'
(R) */
int nf_bgoff; /* Offset between successive lines of
background image (allowing for padding
if used) (R)*/
int ncmp; /* No. of pixels in each direction compressed into
1 for the background calcn. (R)*/
int *ival; /* Returns background value (W)*/
Return: =0 OK;
John W. Campbell
CCLRC Daresbury Laboratory
Last update 4 Feb 1998