.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
