Initial commit

1 files changed, 354 insertions, 0 deletions

diff --git a/noao/twodspec/apextract/doc/aptrace.hlp b/noao/twodspec/apextract/doc/aptrace.hlp
new file mode 100644
index 00000000..3b9ddd38
--- /dev/null
+++ b/noao/twodspec/apextract/doc/aptrace.hlp
@@ -0,0 +1,354 @@
+.help aptrace Sep96 noao.twodspec.apextract
+.ih
+NAME
+aptrace -- Trace spectra for aperture extraction
+.ih
+USAGE
+.nf
+aptrace images
+.fi
+.ih
+PARAMETERS
+.ls input
+List of input images to be traced.
+.le
+.ls apertures = ""
+Apertures to recenter, resize, trace, and extract.  This only applies
+to apertures read from the input or reference database.  Any new
+apertures defined with the automatic finding algorithm or interactively
+are always selected.  The syntax is a list comma separated ranges
+where a range can be a single aperture number, a hyphen separated
+range of aperture numbers, or a range with a step specified by "x<step>";
+for example, "1,3-5,9-12x2".
+.le
+.ls references = ""
+List of reference images to be used to define apertures for the input
+images.  When a reference image is given it supersedes apertures
+previously defined for the input image. The list may be null, "", or
+any number of images less than or equal to the list of input images.
+There are three special words which may be used in place of an image
+name.  The word "last" refers to the last set of apertures written to
+the database.  The word "OLD" requires that an entry exist
+and the word "NEW" requires that the entry not exist for each input image.
+.le
+
+.ls interactive = yes
+Run this task interactively?  If the task is not run interactively then
+all user queries are suppressed and interactive aperture editing and trace
+fitting are disabled.
+.le
+.ls find = yes
+Find the spectra and define apertures automatically?  In order for
+spectra to be found automatically there must be no apertures for the
+input image or reference image defined in the database.
+.le
+.ls recenter = no
+Recenter the apertures?
+.le
+.ls resize = yes
+Resize the apertures?
+.le
+.ls edit = yes
+Edit the apertures?  The \fIinteractive\fR parameter must also be yes.
+.le
+.ls trace = yes
+Trace the apertures?
+.le
+.ls fittrace = yes
+Interactively fit the traced positions by a function?  The \fIinteractive\fR
+parameter must also be yes.
+.le
+
+.ls line = INDEF, nsum = 1
+The dispersion line (line or column perpendicular to the dispersion
+axis) and number of adjacent lines (half before and half after unless
+at the end of the image) used in finding, recentering, resizing,
+and editing operations.  For tracing this is the starting line and
+the same number of lines are summed at each tracing point.  A line of
+INDEF selects the middle of the image along the dispersion axis.
+A positive nsum selects the number of lines to sum while a negative
+value selects a median.  Tracing always uses a sum.
+.le
+.ls step = 10
+Step along the dispersion axis between determination of the spectrum
+positions.
+.le
+.ls nlost = 3
+Number of consecutive steps in which the profile is lost before quitting
+the tracing in one direction.  To force tracing to continue through
+regions of very low signal this parameter can be made large.  Note,
+however, that noise may drag the trace away before it recovers.
+.le
+
+The following parameters are the defaults used to fit the traced positions
+by a function of the dispersion line.  These parameters are those used by
+the ICFIT package.
+.ls function = "legendre"
+Default trace fitting function.  The fitting function types are
+"chebyshev" polynomial, "legendre" polynomial, "spline1" linear spline, and
+"spline3" cubic spline.
+.le
+.ls order = 2
+Default trace function order.  The order refers to the number of
+terms in the polynomial functions or the number of spline pieces in the spline
+functions.
+.le
+.ls sample = "*"
+Default fitting sample.  The sample is given by a set of colon separated
+ranges each separated by either whitespace or commas.  The string "*" refers
+to all points.
+.le
+.ls naverage = 1
+Default number of points to average or median.  Positive numbers
+average that number of sequential points to form a fitting point.
+Negative numbers median that number, in absolute value, of sequential
+points.  A value of 1 does no averaging and each data point is used in the
+.le
+.ls niterate = 0
+Default number of rejection iterations.  If greater than zero the fit is
+used to detect deviant traced positions and reject them before repeating the
+fit.  The number of iterations of this process is given by this parameter.
+.le
+.ls low_reject = 3., high_reject = 3.
+Default lower and upper rejection sigma.  If greater than zero traced
+points deviating from the fit below and above the fit by more than this
+number of times the sigma of the residuals are rejected before refitting.
+.le
+.ls grow = 0.
+Default reject growing radius.  Traced points within a distance given by this
+parameter of any rejected point are also rejected.
+.le
+.ih
+ADDITIONAL PARAMETERS
+I/O parameters and the default dispersion axis are taken from the
+package parameters, the default aperture parameters from
+\fBapdefault\fR, automatic aperture finding parameters from
+\fBapfind\fR, recentering parameters from \fBaprecenter\fR, resizing
+parameters from \fBapresize\fR, and parameters used for centering and
+editing the apertures from \fBapedit\fR.
+
+When this operation is performed from the task \fBapall\fR all parameters
+except the package parameters are included in that task.
+.ih
+DESCRIPTION
+For each image in the input image list the position of the spectrum
+within each aperture are determined at a number of points along the
+dispersion axis and a smooth function is fit to these positions.  The
+fitted curve defines a shift to be added to the aperture center at each
+wavelength.  Other options allow defining apertures using a reference
+image, defining apertures through an automatic finding algorithm (see
+\fBapfind\fR), automatically recentering apertures (see
+\fBaprecenter\fR), automatically resizing apertures (see
+\fBapresize\fR), and interactively editing the apertures prior to
+tracing (see \fBapedit\fR).  Tracing is selected with the parameter
+\fItrace\fR.  If the tracing is done interactively (the
+\fIinteractive\fR parameter set to yes) then the user is queried
+whether or not to trace each image.  The responses are "yes", "no",
+"YES", or "NO", where the upper case queries suppress this query
+for the following images.
+
+The tracing begins with the specified dispersion line.  A dispersion
+line is a line or column of the image perpendicular to the dispersion
+axis.  The dispersion axis is defined in the image header or by the
+package parameter \fIdispaxis\fR.  If the starting dispersion line is
+INDEF then the middle dispersion line of the image is used.  The
+positions of the spectra are determined using the \fBcenter1d\fR
+algorithm and the centering parameters from the \fBapedit\fR task.
+(See help under \fBcenter1d\fR for a description of the one dimensional
+position measuring algorithm.) The positions are redetermined at other
+points along the dispersion axis by stepping from the starting line in
+steps specified by the user.  A number of dispersion lines around each
+dispersion line to be measured may be summed to improve the position
+determinations, particularly for weak profiles.  This number usually is
+set equal to the tracing step.
+
+It is important to understand how to set the step size and the
+relationship between the step size and the centering error radius.
+Larger steps reduce the computational time, which is an important
+consideration.  However, if the step is too large then the tracing may
+fail to follow the systematic changes in the positions of the
+spectrum.  The centering error radius, \fIradius\fR, is used to limit
+the maximum position change between two successive steps.  If the
+positions of a spectrum changes by more than the specified amount or
+the data contrast falls below the \fIthreshold\fR parameter then
+the position is marked as lost.
+
+The centering radius should be large enough to follow changes in the
+spectrum positions from point to point but small enough to detect an error
+in the tracing by a sudden abrupt change in position, such as caused by
+crowding with other spectra or by the disappearance of the spectrum.  The
+\fInlost\fR parameter determines how many consecutive steps the position
+may fail to be found before tracing in that direction is stopped.  If this
+parameter is small the trace will stop quickly upon loss of the profile
+while if it is very large it will continue to try and recover the profile.
+
+The parameter \fIthreshold\fR checks for the vanishing of a spectrum by
+requiring a minimum range in the data used for centering.  If the
+tracing fails when the spectra are strong and well defined the problem
+is usually that the step size is too large and/or the centering error
+radius is too small.
+
+The traced positions of a spectrum include some measurement variation
+from point to point.  Since the actual position of the spectrum in the
+image should be a smooth curve, a function of the dispersion line is fit
+to the measured points.  The fitted function is stored as part of the
+aperture description.  It is an offset to be added to the aperture's
+center as a function of the dispersion line.  Even if the fitting is not
+done interactively plots of the trace and the fit are recorded in the
+plot file or device specified by the parameter \fIplotfile\fR.
+
+Fitting the traced spectrum positions with a smooth function may be
+performed interactively when parameters \fIfittrace\fR and
+\fIinteractive\fR are yes.  This allows changing the default fitting
+parameters.  The function fitting is done with the interactive curve
+fitting tools described under the help topic \fBicfit\fR.  There are
+two levels of queries when fitting the spectrum positions
+interactively; prompts for each image and prompts for each aperture in
+an image.  These prompts may be answered individually with the lower
+case responses "yes" or "no" or answered for all further prompts with
+the responses "YES" or "NO".  Responding with "yes" or "YES" to the
+image prompt allows interactive fitting of the traced positions for the
+spectra.  Prompts are then given for each aperture in the image.  When
+an spectrum is not fit interactively the last set of fitting parameters
+are used (initially the default function and order given by the task
+parameters).  Note that answering "YES" or "NO" to a aperture prompt
+applies to all further aperture in the current image only.  Responding
+with "no" or "NO" to the image prompt fits the spectrum positions for
+all apertures in all images with the last set of fitting parameters.
+
+The tracing may also be done from the interactive aperture editor with
+the 't' key.  The aperture tracing algorithm may be selected from many
+of the tasks in the package with the \fItrace\fR parameter.
+.ih
+APTRACE DATABASE COEFFICIENTS
+The path of an aperture is described by a function that gives an additive
+offset relative to the aperture center as stored under the database keyword
+center.  The function is saved in the database as a series of
+coefficients.  The section containing the coefficients starts with the
+keyword "curve" and the number of coefficients.
+
+The first four coefficients define the type of function, the order
+or number of spline pieces, and the range of the independent variable
+(the line or column coordinate along the dispersion).  The first
+coefficient is the function type code with values:
+
+.nf
+	Code	Type
+	   1	Chebyshev polynomial
+	   2	Legendre polynomial
+	   3	Cubic spline
+	   4	Linear spline
+.fi
+
+The second coefficient is the order (actually the number of terms) of
+the polynomial or the number of pieces in the spline.
+
+The next two coefficients are the range of the independent variable over
+which the function is defined.  These values are used to normalize the
+input variable to the range -1 to 1 in the polynomial functions.  If the
+independent variable is x and the normalized variable is n, then
+
+.nf
+	n = (2 * x - (xmax + xmin)) / (xmax - xmin)
+.fi
+
+where xmin and xmax are the two coefficients.
+
+The spline functions divide the range into the specified number of
+pieces.  A spline coordinate s and the nearest integer below s,
+denoted as j, are defined by
+
+.nf
+	s = (x - xmin) / (xmax - xmin) * npieces
+	j = integer part of s
+.fi
+
+where npieces are the number of pieces.
+
+The remaining coefficients are those for the appropriate function.
+The number of coefficients is either the same as the function order
+for the polynomials, npieces+1 for the linear spline, or npieces + 3
+for the cubic spline.
+
+1. Chebyshev Polynomial
+
+The polynomial can be expressed as the sum
+
+.nf
+	y = sum from i=1 to order {c_i * z_i}
+.fi
+
+where the c_i are the coefficients and the z_i are defined
+interactively as:
+
+.nf
+	z_1 = 1
+	z_2 = n
+	z_i = 2 * n * z_{i-1} - z_{i-2}
+.fi
+
+2. Legendre Polynomial
+
+The polynomial can be expressed as the sum
+
+.nf
+	y = sum from i=1 to order {c_i * z_i}
+.fi
+
+where the c_i are the coefficients and the z_i are defined
+interactively as:
+
+.nf
+	z_1 = 1
+	z_2 = n
+	z_i = ((2*i-3) * n * z_{i-1} - (i-2) * z_{i-2}) / (i - 1)
+.fi
+
+3. Linear Spline
+
+The linear spline is evaluated as
+
+.nf
+	y = c_j * a + c_{j+1} * b
+.fi
+
+where j is as defined earlier and a and b are fractional difference
+between s and the nearest integers above and below
+
+.nf
+	a = (j + 1) - s
+	b = s - j
+.fi
+
+4.  Cubic Spline
+
+The cubic spline is evaluated as
+
+.nf
+	y = sum from i=0 to 3 {c_{i+j} * z_i}
+.fi
+
+where j is as defined earlier.  The term z_i are computed from
+a and b, as defined earlier, as follows
+
+.nf
+	z_0 = a**3
+	z_1 = 1 + 3 * a * (1 + a * b)
+	z_2 = 1 + 3 * b * (1 + a * b)
+	z_3 = b**3
+.fi
+.ih
+EXAMPLES
+.ih
+REVISIONS
+.ls APTRACE V2.11
+The "apertures" parameter can be used to select apertures for resizing,
+recentering, tracing, and extraction.  This parameter name was previously
+used for selecting apertures in the recentering algorithm.  The new
+parameter name for this is now "aprecenter".
+.le
+.ih
+SEE ALSO
+apdefault, apfind, aprecenter, apresize, apedit, apall,
+center1d, icfit, gtools
+.endhelp