.help fit1d Jul85 images.imfit
.ih
NAME
fit1d -- fit a function to image lines
.ih
USAGE	
.nf
fit1d input output type
.fi
.ih
PARAMETERS
.ls input
Images to be fit.  The images may contain image sections.  Only the region
covered by the section will be modified in the output image.
.le
.ls output
Output images to be created or modified.  The number of output images
must match the number of input images.  If an output image does not exist
it is first created and initialized to zero for fit types "fit" and
"difference" and to one for fit type "ratio".
.le
.ls type
Type of output.  The choices are:
.ls fit      
An image created from the function fits to the image lines.
.le
.ls difference
The difference between the image and the fit (i.e. residuals).
.le
.ls ratio
The ratio of the image and fit.
.le
.le
.ls bpm = ""
List of bad pixel masks.  This may be a null string to not use a
bad pixel mask, a single mask that applies to all input images, or
a matching list.  The value may also be !<keyword> to specify a keyword whose
value is the mask to use.
.le
.ls axis = 1
Axis along which the one dimensional fitting is done.  Axis 1 corresponds
to fitting the image lines and axis 2 corresponds to fitting the columns.
.le
.ls interactive = yes
If \fBinteractive\fR is set to yes, a plot of the fit is drawn and the
cursor is available for interactively examining and adjusting the fit.
.le
.ls sample = "*"
Lines or columns to be used in the fits.
.le
.ls naverage = 1
Number of sample points to combined to create a fitting point.
A positive value specifies an average and a negative value specifies
a median.
.le
.ls function = spline3
Function to be fit to the image lines or columns.  The functions are
"legendre" (legendre polynomial), "chebyshev" (chebyshev polynomial),
"spline1" (linear spline), and "spline3" (cubic spline).  The functions
may be abbreviated.
.le
.ls order = 1
The order of the polynomials or the number of spline pieces.
.le
.ls low_reject = 0., high_reject = 0.
Rejection limits below and above the fit in units of the residual sigma.
.le
.ls niterate = 1
Number of rejection iterations.
.le
.ls grow = 0.
When a pixel is rejected, pixels within this distance of the rejected pixel
are also rejected.
.le
.ls graphics = "stdgraph"
Graphics output device for interactive graphics.
.le
.ls cursor = "stdgcur"
Graphics cursor input.
.le
.ih
DESCRIPTION
A one dimensional function is fit to each line or column of the input images.
The function may be a legendre polynomial, chebyshev polynomial,
linear spline, or cubic spline of a given order or number of spline pieces.
The output image is of pixel type real and is formed from the fitted
function values, the difference or residuals of the fit (pixel value -
fitted value), or the ratio between the pixel values and the fitted values.

The output image may exist in which case a section in the input image is
applied to the output image.  Thus, a section on the input image causes only
that part of the output image to be changed.  If the output image does not
exist it is first created with a size given by the full (without a section)
input image and initialized to zero for fit and difference output types
and one for ratio output types.

A bad pixel mask may be specified to exclude data from the fitting.  Any
non-zero value in the mask is excluded.   It appears in the interactive
fitting in the same way as manually deleted points.  The mask is matched to
the input image(s) as described by \fBpmmatch\fR.  The default is matching
in physical coordinates.

The points fit are determined by selecting a sample of lines or columns
specified by the parameter \fIsample\fR and taking either the average or
median of the number of points specified by the parameter \fInaverage\fR.
The type of averaging is selected by the sign of the parameter and the number
of points is selected by the absolute value of the parameter.
The sample points are specified relative to any image sections.

If \fIlow_reject\fR and/or \fIhigh_reject\fR are greater than zero the sigma
of the residuals between the fitted points and the fitted function is computed
and those points whose residuals are less than \fI-low_reject\fR * sigma
and greater than \fIhigh_reject\fR * sigma are excluded from the fit.
Points within a distance of \fIgrow\fR pixels of a rejected pixel are also
excluded from the fit.  The function is then refit without the rejected points.
This rejection procedure may be iterated a number of times given by the
parameter \fIniterate\fR.

The fitting parameters (\fIsample, naverage, function, order, low_reject,
high_reject, niterate, grow\fR)
may be adjusted interactively if the parameter \fIinteractive\fR is yes.
Lines or columns from the image are selected to be fit with the \fBicfit\fR
package.  A single column or line may be chosen or a blank-separated range
may be averaged.  Note that the averaging applies only to the graphed
data used to set the fitting parameters.  The actual image lines and columns
are fit individually.  The interactive cursor mode commands for this package
are described in a separate help entry under "icfit".  Line 1 is automatically
selected for one dimensional images and any number of lines or columns may be
selected for two dimensional images.  Note that the lines or columns are
relative to the input image section; for example line 1 is the first line of
the image section and not the first line of the image.  When an end-of-file or
no line(s) or column(s) are given then the last selected fitting parameters
are used on each line or column of the image.  This step is repeated for
each image in the input list.
.ih
EXAMPLES
1.  To create a smoothed version of an image by fitting the image lines:

    cl> fit1d image fitimage fit

If the interactive flag is set and the image is two dimensional then a prompt
for an image line is printed:

    image: Fit line = 100 200

The selected lines are averaged, graphed, and the interactive options for
setting and fitting the line are used.  Exiting with 'q' or return prompts for
another line if the image is two dimensional.  When the fitting parameters
are suitably set then respond with end-of-file or return to fit all the lines
of the image and create the output image.

2.  To subtract a linear function fit to columns 10 to 20 and 80 to 100 from
columns 10 to 100 and to subtract another linear function fit to lines
110 to 120 and 180 to 200 from columns 110 to 200:

.nf
    cl> fit1d image1[10:100,*] output diff axis=2 sample="1:11,71:91"
    cl> fit1d image1[110:200,*] output diff axis=2 sample="1:11,71:91"
.fi

Pixels outside columns 10 to 100 and 110 to 200 are not affected.  Note that the
sample points are specified relative to the image sections.  The script
\fBbackground\fR is available in other packages for doing background
subtractions.

3.  To determine a small scale response image:

    cl> fit1d image1 flat ratio

The task \fBimred.generic.flat1d\fR is available for making flat field images
by this method with the addition of an extra parameter to limit the data values
for which the ratio is computed.
.ih
SEE ALSO
imred.generic.background, imred.generic.flat1d
xtools.icfit, lineclean, imsurfit
.endhelp
