bscale: Linearly transform the intensities of a list of images

Package: proto

Usage

bscale input output

Parameters

input
List of images to be transformed.
output
List of output transformed images. If the output list is the same as the input list the input images are overwritten.
bzero = "0."
The zero point to be subtracted before applying the scale factor. The options are a numerical value, "mean", "median", or "mode".
bscale = "1."
The scale factor to be applied. The options are a numerical value, "mean", "median", or "mode".
section = ""
The image section to be used for computing the image statistics. If section is "", step is used to define the default image section. Section is used to confine the computation of the mean, median, and mode to a specific region of the image.
step = 10
The step size in pixels which defines the default image section to be used for computing the mean, median, and mode. In image section notation the default section is equivalent to [*:10,*:10,...]. Step is used if the sampling along an axis is not defined by section. Subsampling can significantly reduce the memory and time required for the computation of the mean, median, and mode.
upper = "INDEF"
Upper intensity limit to be used for computing the mean, median, and mode.
lower = "INDEF"
Lower intensity limit to be used for computing the mean, median, and mode.
verbose = yes
Print messages about actions taken by the task?

Description

The specified input images input are linearly transformed in intensity and written to the list of output images output, using the zero point specified by bzero and the scale factor specified by bscale. If the output image list is the same as the input image list the input images will be overwritten.

The expression defining the linear transformation is listed below.

NEW = (OLD - BZERO) / BSCALE

OLD is the input pixel brightness, NEW is the output pixel brightness, BZERO is the zero point offset, and BSCALE is the scale factor. The values of the scaling parameters bzero and bscale may be specified explicitly or the mean, median, or mode of the image may be used for either quantity. If the input image pixel type is short, integer, or long, overflow or truncation may occur.

When one of the scaling parameters is the image mean, median, or mode, then the image mean, median, and mode are calculated. The statistics computation can be restricted to a section of the input image by setting the parameter section. Otherwise the parameter step is used to define a default image section. Subsampling the image can significantly reduce the memory and time requirements for computing the statistics of large images. If numerical values for both the scaling parameters are specified, then the image statistics are not computed. The statistics computation can be limited to given intensity range by setting the parameters lower and upper.

The mean, median, and mode are computed using the following algorithm. Note that this algorithm requires that all the data to used for computing the statistics must be in memory. 

1. The data in the specified image section is read into a buffer.
2. The data is sorted in increasing order of intensity.
3. The points outside upper and lower are excluded.
4. The median is set to the data value at the midpoint of the remaining
   data.
5. The mean and sigma of the remaining data are computed.
6. The histogram bin width (.1*sigma)  and separation (.01*sigma) are
   computed.
7. The location of the bin containing the most data points is determined.
8. The median of the data values in that bin is used to estimate the mode.

Examples

1. Use the mode to subtract a constant background from a list of images. Overwrite the input images. 

cl> bscale *.imh *.imh bzero=mode

2. Scale a list of images to a unit mean. Overwrite the input images. 

cl> bscale *.imh *.imh bscale=mean

3. Scale a list of images to the intensity range 0 to 511, where 234. and 1243. are the original data range. Overwrite the input images. This example uses the CL to calculate bscale. 

cl> bscale.bzero = 234.
cl> bscale.bscale = (1243. - 234.) / 512.
cl> bscale *.imh *.imh

4. Scale an image using a user specified bzero and bscale and create a new output image: 

cl> bscale imagein imageout bzero=0.0 bscale=1.10

5. Median subtract a list of input images using the percent replace facility to create the output image names. 

cl> bscale images*.imh %i%outi%*.imh bzero=median bscale=1.0

6. Repeat the previous example but use the @ file facility for specifying the input and output image lists. 

cl> bscale @infile @outfile bzero=median bscale=1.0

See also

imarith,imcombine