NAME

imsurfit -- fit a surface function to an image

USAGE

imsurfit input, output, xorder, yorder

PARAMETERS

input

List of images to be fit.

output

Output image(s) of type_output .

xorder

The order in x of the polynomials (1 = constant) or the number of polynomial pieces for the bicubic spline.

yorder

The order in y of the polynomials (1 = constant) or the number of polynomial pieces for the bicubic spline.

cross_terms = yes

Cross terms for the polynomials. For example, if xorder = 2 and yorder = 2 then a function of the form z = a + b * x + c * y + d * x * y will be fit.

function = "leg"

Functional for of surface to be fit to the image. The available functions (with minimum match abbreviation) are:

legendre

chebyshev

spline3

spline1

type_output = "fit"

The type of output image. The allowed types (with minimum match abbreviation) are:

clean

The input image with deviant pixels in the good regions replaced by the fitted value.

fit

An image created from the surface fits to the image.

residual

The difference of the input image and the fitted image.

response

The ratio of the input image to the fitted image. All fitted (denominator) pixels below div_min are given a value of 1.

xmedian = 1, ymedian = 1

The x and y dimensions of the box used for median processing. If xmedian > 1 or ymedian is > 1, then the median is calculated for each box and used in the surface fit instead of the individual pixels.

median_percent = 50.

If the number of pixels in the median box is less than median_percent * xmedian * ymedian the box will be omitted from the fit.

upper = 0., lower = 0.

The number of sigma limits for pixel rejection. If upper > 0. or lower > 0. and median processing is turned off, pixel rejection is enabled.

ngrow = 0

The radius in pixels for region growing. Pixels within a distance of ngrow pixels of a rejected pixel are also rejected.

niter = 0

The maximum number of iterations in the rejection cycle. Rejection will be terminated if the number of rejected pixels is zero or the number of iterations equals niter .

regions = "all"

The available options (with minimum match abreviation) are:

all

All points in the image are fit.

rows

The fit is performed on the image rows specified by rows .

columns

The fit is perfomed on the image columns specified by columns .

border

The fit is performed on a border around the image whose width is specified by border .

sections

The fit is performed on image sections listed in the file specified by sections .

circle

The fit is performed on a circular region whose parameters are specified by circle .

invcircle

The fit is performed on a region exterior to the circular region whose parameters are specified by circle .

rows = "*"

When region_type = rows, the string parameter rows specifies the rows to be fit.

columns = "*"

When region_type = columns, the string parameter columns specifies the columns to be fit.

border = "50"

When region_type = border, the string parameter border specifies the width of the border to be fit.

sections = ""

When region_type = sections, the string parameter sections is the name of the file containing the list of image sections to be fit, where Sections may be the standard input (STDIN). The sections must be listed one per line in the following form: x1 x2 y1 y2.

circle = ""

The string parameter circle lists the parameter needed to specify the circle in the following format: xcenter ycenter radius. The three parameters must be integers.

div_min = INDEF

When type_output = response all divisions in which the fitted value is below div_min are set to the value 1.

DESCRIPTION

A surface is fit to selected portions of the input image. The user may elect to fit the whole image, region_type = all, selected rows, region_type = rows, selected columns, region_type = columns, a border around the image, region_type = border or image sections, region_type = sections. If the sections option is enabled the user must supply the name of the file containing a list of sections, sections = list, or enter them from the standard input. In either case the sections must be listed one per line in the following form: x1 x2 y1 y2.

The parameter surface_type may be a "legendre" polynomial, "chebyshev" polynomial, a cubic spline ("spline3") or a linear spline ("spline1"). The order of the polynomials is selected in both x and y. Cross terms for the polynomial surfaces are optional. For the cubic spline the parameters xorder and yorder specify the number of polynomial pieces to be fit to the surface in each direction.

The output image may be the fitted image, the difference between the input and the fitted image, the ratio of the input to the fitted image or the input image with deviant pixels in the fitted regions replaced with the fitted values, according to whether type_output = fit, residual, response or clean. If type_output = response then pixels in the fitted image with values < div_min are replaced by 1. If type_output = clean then at least one of upper or lower must be > 0.

Pixel rejection is enabled if median processing is turned off, niter > 0, and at least one of the parameters upper and lower is > 0. Region growing can be turned on by setting ngrow > 0, in which case all pixels within a radius ngrow of a deviant pixel will be rejected.

EXAMPLES

1. To create a smoothed version of an image:

	cl> imsurfit m74 m74smooth 5 10 function=spline3

2. To create a smooted version of an image using median processing:

	cl> imsurfit m74 m74med 5 10 function=spline3 \
	>>> xmed=5 ymed=5

3. To subtract a constant background from an image:

	cl> imsurfit abell30 abell30bck 1 1 function=leg \
	>>> type=resid

4. To make a ratio image using signals above 1000 units:

	cl> imsurfit n7006 n7006ratio 20 20 function=spline3 \
	>>> type=response div_min=1000

TIMINGS

Fitting and subtracting a constant from a 512 by 512 IRAF image requires ~35 cpu seconds. Approximately 130 cpu seconds are required to fit a second degree polynomial in x and y (including cross-terms) to a 100 pixel wide border around a 512 by 512 IRAF image, and to subtract the fitted image from the input image. To produce a smooth 512 by 512 IRAF image using a 10 by 10 bicubic spline requires ~300 cpu seconds. Timings refer to a VAX 11/750 + fpa.

NOTES

The surface fitting code uses the IRAF SURFIT math routines, which have been optimized for image fitting . The routines which fit selected portions of the image, perform pixel rejection and region growing, and create and maintain a list of rejected pixels utilize the ranges and pixlist packages of routines currently maintained in the images directory. These will be replaced by more general ranges and image masking routines in the future.