Repatch (from linux) of OSX IRAF

1 files changed, 180 insertions, 0 deletions

diff --git a/noao/twodspec/apextract/doc/apfind.hlp b/noao/twodspec/apextract/doc/apfind.hlp
new file mode 100644
index 00000000..65260394
--- /dev/null
+++ b/noao/twodspec/apextract/doc/apfind.hlp
@@ -0,0 +1,180 @@
+.help apfind Sep96 noao.twodspec.apextract
+.ih
+NAME
+apfind -- Find spectra and define apertures automatically
+.ih
+USAGE
+apfind input
+.ih
+PARAMETERS
+.ls input
+List of input images in which spectra are to be identified and
+apertures defined automatically.
+.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 = no
+Run this task interactively?  If the task is not run interactively then
+all user queries are suppressed and interactive aperture editing is
+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 and the
+parameter \fInfind\fR must be greater than zero.
+.le
+.ls recenter = no
+Recenter the apertures?
+.le
+.ls resize = no
+Resize the apertures?
+.le
+.ls edit = yes
+Edit the apertures?  The \fIinteractive\fR parameter must also be yes.
+.le
+
+.ls line = INDEF
+The dispersion line (line or column perpendicular to the dispersion axis) to
+be used in finding the spectra.  A value of INDEF selects the middle of the
+image.
+.le
+.ls nsum = 1
+Number of dispersion lines to be summed or medianed.  The lines are taken
+around the specified dispersion line.  A positive value sums lines and
+a negative value medians lines.
+.le
+.ls nfind = 1
+Maximum number of apertures to be defined.  This is a query parameter
+so the user is queried for a value except when given explicitly on
+the command line.
+.le
+.ls minsep = 5.
+Minimum separation between spectra.  Weaker spectra or noise within this
+distance of a stronger spectrum are rejected.
+.le
+.ls maxsep = 1000.
+Maximum separation between adjacent spectra.  This parameter
+is used to identify missing spectra in uniformly spaced spectra produced
+by fiber spectrographs.  If two adjacent spectra exceed this separation
+then it is assumed that a spectrum is missing and the aperture identification
+assignments will be adjusted accordingly.
+.le
+.ls order = "increasing"
+When assigning aperture identifications order the spectra "increasing"
+or "decreasing" with increasing pixel position (left-to-right or
+right-to-left in a cross-section plot of the image).
+.le
+.ih
+ADDITIONAL PARAMETERS
+I/O parameters and the default dispersion axis are taken from the
+package parameters, the default aperture parameters are taken from the
+task \fBapdefault\fR, and parameters used for centering and editing the
+apertures are taken 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 spectra are identified and
+default apertures defined.  The automatic aperture finding is performed
+only if 1) there are no apertures defined for the reference image, 2)
+there are no apertures defined for the input image, 3) the parameter
+\fIfind\fR is yes, and 4) the parameter \fInfind\fR is greater than
+zero.
+
+The automatic finding algorithm uses the following steps.  First, all local
+maxima are found.  The maxima are sorted by peak value and the weaker
+of the peaks separated by less than the value given by the parameter
+\fIminsep\fR are rejected.  Finally, at most the \fInfind\fR strongests
+peaks are kept.  \fBNfind\fR is a query parameter, so if it is not
+specified explicitly on the command line, the desired number of spectra
+to be found is requested.  After the peaks have been found the
+\fBcenter1d\fR algorithm is used to refine the centers of the
+profiles.  Apertures having the default parameters set with the task
+\fBapdefault\fR are defined at each center.  This algorithm is also
+available with the 'f' key in the task \fBapedit\fR with the change that
+existing apertures are kept and count toward the maximum number
+specified by \fBnfind\fR.
+
+The automatic assignment of aperture numbers, beam numbers, and titles
+has several options.  The simplest is when no aperture identification
+table, parameter \fIapidtable\fR, is specified and the maximum separation
+parameter, \fImaxsep\fR, is very large.  In this case the aperture and
+beam numbers are sequential starting from one and numbered either from
+left-to-right or right-to-left depending on the \fIorder\fR parameter.
+There are no aperture titles in this case.  If two adjacent spectra are
+separated by more than the specified maximum then the aperture numbers
+jump by the integer part of the ratio of the separation to the
+specified maximum separation.  This is used when the image is expected
+to have evenly spaced spectra, such as in multifiber spectrographs, in
+which some may be missing due to broken fibers.  Finally, the
+aperture identification table (either a text file or an image
+having a set of SLFIBnnn keyowrds) may contain lines with aperture number,
+beam number, and (optional) title.  The sequential numbers are then
+indices into this table.  Note that the skipping of missing spectra and
+the ordering applies to entries in this table as well.
+
+The ways in which the automatic method can fail for evenly spaced
+spectra with missing members are when the first spectrum is missing on
+the side from which the ordering begins and when the expected rather
+the actual number of spectra is used.  In the first case one can use
+the interactive 'o' key of the aperture editing facility to specify the
+identity of any aperture and then all other apertures will be
+appropriately reidentified.  If more spectra are sought than actually
+exist then noise spikes may be mistakenly found.  This problem can be
+eliminated by specifying the actual number of spectra or minimized by
+using the threshold centering parameter.
+
+The \fIrecenter\fR parameter allows recentering apertures if defined by
+a reference image.  Since the purpose of this task is to find new
+apertures it is usually the case that there are no reference images and
+recentering is not done.  The default apertures are of fixed width.
+The \fIresize\fR parameter may be used to adjust the widths in a
+variety of ways.  The aperture positions and any other parameters may
+also be edited with the aperture editing function if selected by the
+\fIapedit\fR parameter and the task is run interactively.
+
+If the task is interactive the user is queried whether to perform
+various steps on each image.  The queries may be answered with one of
+the four values "yes", "no", "YES" and "NO", where an upper case
+response suppresses all further queries to this question.
+
+The aperture finding algorithm may be selected from nearly every task
+in the package.
+.ih
+EXAMPLES
+	cl> apfind image nfind=10
+.ih
+.ih
+REVISIONS
+.ls APFIND 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".
+
+The aperture ID table information may now be contained in the
+image header under the keywords SLFIBnnn.
+.le
+SEE ALSO
+center1d, apdefault, aprecenter, apresize, apedit, apall
+.endhelp