NOTES

## 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.