Initial commit

3 files changed, 532 insertions, 0 deletions

diff --git a/pkg/images/imfit/doc/fit1d.hlp b/pkg/images/imfit/doc/fit1d.hlp
new file mode 100644
index 00000000..5b49f45f
--- /dev/null
+++ b/pkg/images/imfit/doc/fit1d.hlp
@@ -0,0 +1,177 @@
+.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
diff --git a/pkg/images/imfit/doc/imsurfit.hlp b/pkg/images/imfit/doc/imsurfit.hlp
new file mode 100644
index 00000000..0aa46a97
--- /dev/null
+++ b/pkg/images/imfit/doc/imsurfit.hlp
@@ -0,0 +1,226 @@
+.help imsurfit Feb88 images.imfit
+.ih
+NAME
+imsurfit -- fit a surface function to an image
+.ih
+USAGE	
+imsurfit input, output, xorder, yorder
+.ih
+PARAMETERS
+.ls input
+List of images to be fit.
+.le
+.ls output
+Output image(s) of \fItype_output\fR.
+.le
+.ls xorder
+The order in x of the polynomials (1 = constant) or the number of polynomial
+pieces for the bicubic spline.
+.le
+.ls yorder
+The order in y of the polynomials (1 = constant) or the number of polynomial
+pieces for the bicubic spline.
+.le
+.ls cross_terms = yes
+Cross terms for the polynomials. For example, if \fIxorder\fR = 2 and
+\fIyorder\fR = 2
+then a function of the form z = a + b * x + c * y + d * x * y will be fit.
+.le
+.ls function = "leg"
+Functional for of surface to be fit to the image. The available functions
+(with minimum match abbreviation) are:
+.ls legendre
+.le
+.ls chebyshev
+.le
+.ls spline3
+.le
+.ls spline1
+.le
+.le
+.ls type_output = "fit"
+The type of output image.  The allowed types (with minimum match abbreviation)
+are:
+.ls clean
+The input image with deviant pixels in the good regions replaced by the
+fitted value.
+.le
+.ls fit  
+An image created from the surface fits to the image.
+.le
+.ls residual
+The difference of the input image and the fitted image.
+.le
+.ls response
+The ratio of the input image to the fitted image.
+All fitted (denominator) pixels below \fIdiv_min\fR are given a value of 1.
+.le
+.le
+.ls xmedian = 1, ymedian = 1
+The x and y dimensions of the box used for median processing.
+If \fIxmedian\fR > 1 or \fIymedian\fR is > 1,
+then the median is calculated for each box and used in the surface
+fit instead of the individual pixels.
+.le
+.ls median_percent = 50.
+If the number of pixels in the median box is less than \fImedian_percent\fR *
+\fIxmedian\fR * \fIymedian\fR the box will be omitted from the fit.
+.le
+.ls upper = 0., lower = 0.
+The number of sigma  limits for pixel rejection. If \fIupper\fR > 0. or
+\fIlower\fR > 0. and median processing is turned off,
+pixel rejection is enabled.
+.le
+.ls ngrow = 0
+The radius in pixels for region growing.
+Pixels within a distance of \fIngrow\fR pixels of
+a rejected pixel are also rejected.
+.le
+.ls 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 \fIniter\fR.
+.le
+.ls regions = "all"
+The available options (with minimum match abbreviation) are:
+.ls all
+All points in the image are fit.
+.le
+.ls rows
+The fit is performed on the image rows specified by \fIrows\fR.
+.le
+.ls columns
+The fit is performed on the image columns specified by \fIcolumns\fR.
+.le
+.ls border
+The fit is performed on a border around the image whose width is specified
+by \fIborder\fR.
+.le
+.ls sections
+The fit is performed on image sections listed in the file specified
+by \fIsections\fR.
+.le
+.ls circle
+The fit is performed on a circular region whose parameters are specified by
+\fIcircle\fR.
+.le
+.ls invcircle
+The fit is performed on a region exterior to the circular region whose
+parameters are specified by \fIcircle\fR.
+.le
+.le
+.ls rows = "*"
+When \fIregion_type\fR = 'rows', the string parameter \fIrows\fR specifies
+the rows to be fit.
+.le
+.ls columns = "*"
+When \fIregion_type\fR = 'columns', the string parameter \fIcolumns\fR
+specifies the columns to be fit.
+.le
+.ls border = "50"
+When \fIregion_type\fR = 'border', the
+string parameter \fIborder\fR specifies the width of the border to be fit.
+.le
+.ls sections = ""
+When \fIregion_type\fR = 'sections', the
+string parameter \fIsections\fR is the name of the  file containing the list of
+image sections to be fit, where \fISections\fR may be the standard
+input (STDIN).
+The sections must be listed one per line in the following form: x1 x2 y1 y2.
+.le
+.ls circle = ""
+The string parameter \fIcircle\fR lists the parameter needed to specify
+the circle in the following format: xcenter ycenter radius. The three
+parameters must be integers.
+.le
+.ls div_min = INDEF
+When \fItype_output\fR = 'response' all divisions in which the fitted value
+is below \fIdiv_min\fR are set to the value 1.
+.le
+.ih
+DESCRIPTION
+A surface is fit to selected portions of the input image.
+The user may elect to fit the whole image, \fIregion_type\fR = 'all',
+selected rows, \fIregion_type\fR = 'rows', selected columns,
+\fIregion_type\fR = 'columns', a
+border around the image, \fIregion_type\fR = 'border' or image sections, 
+\fIregion_type\fR = 'sections'. If the sections  option is enabled the user
+must supply the name of the file containing a list of sections,
+\fIsections\fR = '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 \fIsurface_type\fR 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 \fIxorder\fR and \fIyorder\fR 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 \fItype_output\fR =
+'fit', 'residual',
+'response' or 'clean'. If \fItype_output\fR = 'response' then pixels in the
+fitted image with values < \fIdiv_min\fR are replaced by 1.
+If \fItype_output\fR =
+'clean' then at least one of \fIupper\fR or \fIlower\fR must be > 0.
+
+Pixel rejection is enabled if median processing is turned off,
+\fIniter\fR > 0,
+and at least one of the parameters \fIupper\fR and \fIlower\fR is > 0.
+Region growing
+can be turned on by setting \fIngrow\fR > 0, in which case all pixels within
+a radius ngrow of a deviant pixel will be rejected.
+
+.ih
+EXAMPLES
+1. To create a smoothed version of an image:
+
+.nf
+	cl> imsurfit m74 m74smooth 5 10 function=spline3
+.fi
+
+2. To create a smoothed version of an image using median processing:
+
+.nf
+	cl> imsurfit m74 m74med 5 10 function=spline3 \
+	>>> xmed=5 ymed=5
+.fi
+
+3. To subtract a constant background from an image:
+
+.nf
+	cl> imsurfit abell30 abell30bck 1 1 function=leg \
+	>>> type=resid
+.fi
+
+4. To make a ratio image using signals above 1000 units:
+
+.nf
+	cl> imsurfit n7006 n7006ratio 20 20 function=spline3 \
+	>>> type=response div_min=1000
+.fi
+
+.ih
+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.
+
+.ih
+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.
+.endhelp
diff --git a/pkg/images/imfit/doc/lineclean.hlp b/pkg/images/imfit/doc/lineclean.hlp
new file mode 100644
index 00000000..9ce2b95f
--- /dev/null
+++ b/pkg/images/imfit/doc/lineclean.hlp
@@ -0,0 +1,129 @@
+.help lineclean May85 images.imfit
+.ih
+NAME
+lineclean -- replace deviant pixels in image lines
+.ih
+USAGE	
+.nf
+lineclean input output
+.fi
+.ih
+PARAMETERS
+.ls input
+Input images to be cleaned.
+.le
+.ls output
+Output cleaned images.  The number of output images must be the same as the
+number of input images.
+.le
+.ls sample = "*"
+Columns to be used in fitting the cleaning function.
+.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
+Cleaning function to be fit to the image lines.  The functions are:
+.ls legendre
+Legendre polynomial of the specified order.
+.le
+.ls chebyshev
+Chebyshev polynomial of the specified order.
+.le
+.ls spline1
+Linear spline of the specified number of pieces.
+.le
+.ls spline3
+Cubic spline of the specified number of pieces.
+.le
+.le
+.ls order = 1
+The order of the polynomials or the number of spline pieces.
+.le
+.ls low_reject = 2.5, high_reject = 2.5
+Rejection limits below and above the fit in units of the residual sigma.
+.le
+.ls niterate = 1
+Number of rejection iterations.
+.le
+.ls grow = 1.
+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 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.
+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.  Finally, the
+rejected points in the input image are replaced by the fitted values
+to create the output image lines.
+
+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 cleaned.  If the output image does not
+exist it is first created by making a copy of the full (without a section)
+input image.
+
+The points fit are determined by selecting a sample of 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 section.
+
+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 from the image are selected to be fit with the \fBicfit\fR package.
+For images of greater than two dimensions sets of numbers giving the
+2nd, 3rd, etc. coordinates are entered.
+The image lines are specified relative to any image section.
+When an end-of-file or no line is given then the last selected fitting
+parameters are used on each line of the image.  This step is repeated for
+each image in the input list.  The interactive options are described
+in the help information \fBicfit\fR.
+.ih
+EXAMPLES
+1. To clean pixels deviating by more than 2.5 sigma:
+
+	cl> lineclean image cleanimage
+
+If the interactive flag is set then a prompt for an image line is
+printed:
+
+	image: Fit line = 100
+
+For a one or two dimensional image the line number is entered (1 for a one
+dimensional image).  For a three dimensional image two numbers are entered.
+For example:
+
+	image: Fit line = 10 2
+
+for line 10 of the second image plane.
+
+The selected line is graphed and the interactive options for setting and
+fitting the line are used.  Data points marked with diamonds indicate
+points to be replaced by the fitted value.  Exiting with 'q' or return
+prompts for another line.  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.
+.ih
+SEE ALSO
+fit1d, xtools.icfit, imsurfit
+.endhelp