From 40e5a5811c6ffce9b0974e93cdd927cbcf60c157 Mon Sep 17 00:00:00 2001
From: Joe Hunkeler <jhunkeler@gmail.com>
Date: Tue, 11 Aug 2015 16:51:37 -0400
Subject: Repatch (from linux) of OSX IRAF

---
 noao/twodspec/apextract/doc/apedit.hlp | 374 +++++++++++++++++++++++++++++++++
 1 file changed, 374 insertions(+)
 create mode 100644 noao/twodspec/apextract/doc/apedit.hlp

(limited to 'noao/twodspec/apextract/doc/apedit.hlp')

diff --git a/noao/twodspec/apextract/doc/apedit.hlp b/noao/twodspec/apextract/doc/apedit.hlp
new file mode 100644
index 00000000..324f6e5d
--- /dev/null
+++ b/noao/twodspec/apextract/doc/apedit.hlp
@@ -0,0 +1,374 @@
+.help apedit Sep96 noao.twodspec.apextract
+.ih
+NAME
+apedit -- Edit apertures
+.ih
+USAGE
+apedit input
+.ih
+PARAMETERS
+.ls input
+List of input images for which apertures are to be edited.
+.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.
+If the reference image list is shorter than the input image list the
+last reference image is used for the remaining 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 = no
+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 = 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 graphed.  A value of INDEF uses the middle of the image.
+.le
+.ls nsum = 10
+Number of dispersion lines to be summed or medianed.  The lines are taken
+around the specified dispersion line.  A positive nsum selects a sum of
+lines and a negative selects a median of lines.
+.le
+.ls width = 5.
+Width of spectrum profiles.  This parameter is used for the profile
+centering algorithm in this and other tasks.
+.le
+.ls radius = 5.
+The profile centering error radius for the centering algorithm.
+.le
+.ls threshold = 0.
+Centering threshold for the centering algorithm.  The range of pixel intensities
+near the initial centering position must exceed this threshold.
+.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.  Parameters for the various functions of finding,
+recentering, and resizing are taken from the parameters for the
+appropriate task.
+
+When this operation is performed from the task \fBapall\fR all parameters
+except the package parameters are included in that task.
+.ih
+CURSOR KEYS
+When editing the apertures interactively the following cursor keys are
+available.
+
+.nf
+?    Print help
+a    Toggle the ALL flag
+b an Set background fitting parameters
+c an Center aperture(s)
+d an Delete aperture(s)
+e an Extract spectra (see APSUM)
+f    Find apertures up to the requested number (see APFIND)
+g an Recenter aperture(s) (see APRECENTER)
+i  n Set aperture ID
+j  n Set aperture beam number
+l ac Set lower limit of current aperture at cursor position
+m    Define and center a new aperture on the profile near the cursor
+n    Define a new aperture centered at the cursor
+o  n Enter desired aperture number for cursor selected aperture and
+     remaining apertures are reordered using apidtable and maxsep
+     parameters (see APFIND for ordering algorithm)
+q    Quit
+r    Redraw the graph
+s an Shift the center(s) of the current aperture to the cursor
+     position
+t ac Trace aperture positions (see APTRACE)
+u ac Set upper limit of current aperture at cursor position
+w    Window the graph using the window cursor keys
+y an Set aperture limits to intercept the data at the cursor y
+     position
+z an Resize aperture(s) (see APRESIZE)
+.  n Select the aperture nearest the cursor for current aperture
++  c Select the next aperture (in ID) to be the current aperture
+-  c Select the previous aperture (in ID) to be the current aperture
+I    Interrupt task immediately.  Database information is not saved.
+.fi
+
+The letter a following the key indicates if all apertures are affected when
+the ALL flag is set.  The letter c indicates that the key affects the
+current aperture while the letter n indicates that the key affects the
+aperture whose center is nearest the cursor.
+.ih
+COLON COMMANDS
+
+.nf
+:show [file]	   Print a list of the apertures (default STDOUT)
+:parameters [file] Print current parameter values (default STDOUT)
+:read [name]       Read from database (default current image)
+:write [name]      Write to database (default current image)
+.fi
+
+The remaining colon commands are task parameters and print the current
+value if no value is given or reset the current value to that specified.
+Use :parameters to see current parameter values.
+
+.nf
+:apertures      :apidtable      :avglimits      :b_function
+:b_grow         :b_high_reject  :b_low_reject   :b_naverage
+:b_niterate     :b_order        :b_sample       :background
+:bkg            :center         :clean          :database
+:extras         :gain           :image          :line
+:llimit         :logfile        :lower          :lsigma
+:maxsep         :minsep         :npeaks         :nsubaps
+:nsum           :order          :parameters     :peak
+:plotfile       :r_grow         :radius         :read
+:readnoise      :saturation     :shift          :show
+:skybox         :t_function     :t_grow         :t_high_reject
+:t_low_reject   :t_naverage     :t_niterate     :t_nsum
+:t_order        :t_sample       :t_step         :t_width
+:threshold      :title          :ulimit         :upper
+:usigma         :weights        :width          :write
+:ylevel		:t_nlost
+.fi
+.ih
+DESCRIPTION
+For each image in the input image list, apertures are defined and edited
+interactively.  The aperture editor is invoked when the parameters
+\fIinteractive\fR and \fIedit\fR are both yes.  When this is the case
+the task will query whether to edit each image.  The responses are
+"yes", "no", "YES", and "NO", where the upper case responses suppress
+queries for all following images.
+
+When the aperture editor is entered a graph of the image lines or
+columns specified by the parameters \fIline\fR and \fInsum\fR is
+drawn.  In the \fBapextract\fR package a dispersion line is either a
+line or column in the image at one point along the dispersion axis.
+The dispersion axis may be defined in the image header under the
+keyword DISPAXIS or by the package parameter \fIdispaxis\fR.  The
+parameter \fBnsum\fR determines how many dispersion lines surrounding
+the specified dispersion line are summed or medianed.  This improves the
+signal in the profiles of weaker spectra.  Once the graph is drawn an
+interactive cursor loop is entered.  The set of cursor keys and colon
+commands is given above and may be printed when the task is running using
+the '?' key.  The CURSOR MODE keys and graph formatting options are also
+available (see \fBcursor\fR and \fBgtools\fR).
+
+A status line, usually at the bottom of the graphics terminal,
+indicates the current aperture and shows the ALL flag, 'a' key, if set.  The
+concept of the current aperture is used by several of the aperture
+editing commands.  Other commands operate on the aperture whose center
+is nearest the cursor.  It is important to know which commands operate
+on the current aperture and which operate on the nearest aperture to
+the cursor.
+
+The cursor keys and colon commands are used to define new apertures,
+delete existing apertures, modify the aperture number, beam number,
+title, center, and limits, set background fitting parameters, trace the
+positions of the spectra in the apertures, and extract aperture
+spectra.  When creating new apertures default parameters are supplied
+in two ways; if no apertures are defined then the default parameters
+are taken from the task \fBapdefault\fR while if there is a current
+aperture then a copy of its parameters are made.
+
+The keys for creating a new aperture are 'm' and 'n' and 'f'.  The key
+'m' marks a new aperture and centers the aperture on the profile
+nearest the cursor.  The centering algorithm is described under the
+help topic \fBcenter1d\fR and the parameters controlling the centering are
+\fIwidth\fR, \fIradius\fR, and \fIthreshold\fR.  The key 'n' defines a
+new aperture at the position of the cursor without centering.  This is
+used if there is no spectrum profile such as when defining sky apertures
+or when defining apertures in extended profiles.  The 'f' key finds new
+apertures using the algorithm described in the task \fBapfind\fR.  The
+number of apertures found in this way is limited by the parameter
+\fBnfind\fR and the number includes any previously defined
+apertures.  The new aperture number, beam number, and title are assigned using
+the aperture assignment algorithm described in \fBapfind\fR.
+
+The aperture number for the aperture \fInearest\fR the cursor is changed
+with the 'j' key and the beam number is changed with the 'k' key.  The
+user is prompted for a new aperture number or beam number.  The
+aperture title may be set or changed with the :title colon command.
+
+The 'o' key may be used to reorder or correct the aperture
+identifications and beam numbers.  This is useful if the aperture
+numbers become disordered due to deletions and additions or if the
+first spectrum is missing when using the automatic identification
+algorithm.  An aperture number is requested for the aperture pointed to
+by the cursor.  The remaining apertures are reordered relative to this
+aperture number.  There is a aperture number, beam number, and title
+assignment algorithm which uses information about the maximum
+separation between consecutive apertures, the direction of increasing
+aperture numbers, and an optional aperture identification table.  See
+\fBapfind\fR for a description of the algorithm.
+
+After defining a new aperture it becomes the current aperture.  The
+current aperture is indicated on the status line and the '.', '+', and
+'-' keys are used to select a new current aperture.
+
+Apertures are deleted with 'd' key.  The aperture \fInearest\fR the
+cursor is deleted.
+
+The aperture center may be changed with the 'c', 's', and 'g' keys and the
+":center value" colon command.  The 'c' key applies the centering algorithm
+to the aperture \fInearest\fR the colon.  The 's' key shifts the center
+of the \fIcurrent\fR aperture to the position of the cursor.  The 'g'
+applies the \fBaprecenter\fR algorithm.  The :center command sets the
+center of the \fIcurrent\fR aperture to the value specified.  Except
+for the last option these commands may be applied to all apertures
+if the ALL flag is set.
+
+The aperture limits are defined relative to the aperture center.  The
+limits may be changed with the 'l', 'u', 'y', and 'z' keys and with the
+":lower value" and ":upper value" commands.  The 'l' and 'u' keys set
+the lower and upper limits of the \fIcurrent\fR aperture at the position
+of the cursor.  The colon commands allow setting the limits explicitly.
+The 'y' key defines both limits for the \fInearest\fR aperture as
+points at which the y cursor position intercepts the data profile.
+This requires that the aperture include a spectrum profile and that
+the y cursor value lie below the peak of the profile.  The 'z'
+key applies the \fBapresize\fR algorithm.  Except for the colon
+commands these commands may be applied to all apertures if the ALL
+flag is set.
+
+The key 'b' modifies the background fitting parameters for the aperture
+\fInearest\fR the cursor.  The default background parameters are
+specified by the task \fBapdefault\fR.  Note that even though
+background parameters are defined, background subtraction is not
+performed during extraction unless specified.
+When the 'b' key is used the \fBicfit\fR graphical interface is entered
+showing the background regions and function fit for the current image
+line.  Note that the background regions are specified relative to
+the aperture center and follows changes in the aperture position.
+
+The two types of
+extraction which may be specified are to average all points within
+a set of background regions or fit a function to the points in
+the background regions.  In the first case only the background sample
+parameter is used.  In the latter case the other parameters are
+also used in conjunction with the \fBicfit\fR function fitting commands.
+See \fBapbackground\fR for more on the background parameters.
+
+Each aperture may have different background
+fitting parameters but newly defined apertures inherit the background
+fitting parameters of the last current aperture.  This will usually be
+satisfactory since the background regions are defined relative to the
+aperture center rather than in absolute coordinates.  If the ALL flag
+is set then all apertures will be given the same background
+parameters.
+
+The algorithms used in the tasks \fBapfind, aprecenter, apresize, aptrace\fR,
+and \fBapsum\fR are available from the editor with the keys 'f', 'g', 'z',
+'t', and 'e'
+respectively.  Excluding finding, if the ALL flag is not set then the
+nearest aperture
+to the cursor is used.  This allows selective recentering, resizing,
+tracing and extracting.
+If the ALL flag is set then all apertures are traced or extracted.
+When extracting the output, rootname and profile name are queried.
+
+Some general purpose keys window the graph 'w' using the \fBgtools\fR
+commands, redraw the graph 'r', and quit 'q'.
+
+The final cursor key is the 'a' key.  The cursor keys which modify the
+apertures were defined as operating on either the aperture nearest the
+cursor or the current aperture.  The 'a' key allows these keys to
+affect all the apertures simultaneously.  The 'a' key sets a flag which
+is shown on the status line when it is set.  When set, the operation on
+one aperture is duplicated on the remaining apertures.  The operations
+which apply to all apertures are set background 'b', center 'c', delete
+'d', extract 'e', recenter 'g', set lower limit 'l', shift 's', trace
+'t', set upper limit 'u', set limits at the y cursor 'y', and resize
+'z'.  The 'b', 'l', 's', and 'u' keys first set the background,
+aperture limits, or shift for the appropriate aperture and then are
+applied to the other apertures relative to their centers.
+
+All the parameters used in any of the operations may be examined or
+changed through colon commands.  The :parameters command lists all
+parameter values and :show lists the apertures.  The :read and :write
+are used to force an update or save the current apertures and to read
+apertures for the current image or from some other image.  The commands
+all have optional arguments.  For the commands which show information
+the argument specifies a file to which the information is to be
+written.  The default is the standard output.  The database read and
+write and the change image commands take an image name.  If an image
+name is not given for the read and write commands the
+current image name is used.  The change image command default is to
+print the current image name.  The remaining commands take a value.  If
+a value is not given then the current value is printed.
+
+The aperture editor may be selected from nearly every task using the
+\fBedit\fR parameter.
+.ih
+EXAMPLES
+The aperture editor is a very flexible and interactive tool
+for which it is impossible illustrate all likely uses.  The following
+give some simple examples.
+
+1.  To define and edit apertures for image "n1.001":
+
+	cl> apedit n1.001
+
+2.  To define apertures for one image and then apply them to several other
+images:
+
+.nf
+	cl> apedit n1.* ref=n1.001
+	Edit apertures for n1.001? (yes)
+	Edit apertures for n1.002? (yes) NO
+.fi
+
+Answer "yes" to the first query for editing n1.001.  To
+the next query (for n1.002) respond with "NO".  The remaining
+images then will not be edited interactively.  Note that after
+defining the apertures for n1.001 they are recorded in the database
+and subsequent images will be able to use them as reference apertures.
+
+3.  Using the ":image name" and ":read image" colon commands and the
+'f', 'g', 'z', 't' and 'e' keys the user can perform all the functions
+available in the package without ever leaving the editor.  The 'a' key
+to set the ALL flag is very useful when dealing with many spectra in a
+single image.
+.ih
+.ih
+REVISIONS
+.ls APEDIT 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
+.nf
+apdefault, apfind, aprecenter, apresize, aptrace, apsum, apall
+center1d, cursor, gtools, icfit
+.fi
+.endhelp
-- 
cgit 

