Initial commit

13 files changed, 1191 insertions, 0 deletions

diff --git a/pkg/xtools/doc/Notes b/pkg/xtools/doc/Notes
new file mode 100644
index 00000000..4fd91876
--- /dev/null
+++ b/pkg/xtools/doc/Notes
@@ -0,0 +1,42 @@
+------
+# GETDATATYPE -- Convert a character to an IRAF data type (one of TY_*)
+# Recognized character codes "bcusilrdx"
+
+int procedure getdatatype (c)
+
+char	c
+______
+DECODE_RANGES:  See help text in source code or ranges.doc.
+______
+GET_NEXT_NUMBER:   See help text in source code or ranges.doc.
+______
+IS_IN_RANGE:   See help text in source code or ranges.doc.
+______
+# EXTREMA -- Find the extrema in a set of x and y data points
+
+Help text is in the source code
+______
+# PEAKS -- Find the peaks in a set of x and y data points
+
+Help text is in the source code
+______
+# CLGSEC -- Get an image section and decode it.
+#
+# A section string may be either a null string or bracketed by [].
+# The arrays x1, x2, and step are initialized to FIRST, LAST, and STEP.
+# The number of subscripts decoded is returned in nsubscripts.
+# This routine uses the same decode routine as IMIO.
+
+
+define	FIRST	1
+define	LAST	MAX_LONG
+define	STEP	1
+
+procedure clgsec (prompt, section, x1, x2, step, nsubscripts)
+
+char	prompt[ARB]
+char	section[ARB]
+long	x1[IM_MAXDIM]
+long	x2[IM_MAXDIM]
+long	step[IM_MAXDIM]
+int	nsubscripts
diff --git a/pkg/xtools/doc/center1d.hlp b/pkg/xtools/doc/center1d.hlp
new file mode 100644
index 00000000..742fa7cb
--- /dev/null
+++ b/pkg/xtools/doc/center1d.hlp
@@ -0,0 +1,147 @@
+.help center1d May93 xtools
+.ih
+NAME
+center1d -- One dimensional centering
+.ih
+SYNOPSIS
+.nf
+center = center1d (initial, data, npts, width, type, radius, threshold)
+
+real	initial			# Initial guess
+real	data[npts]		# Data points
+int	npts			# Number of data points
+real	width			# Feature width
+int	type			# Feature type
+real	radius			# Centering radius
+real	threshold		# Detection threshold
+.fi
+.ih
+ARGUMENTS
+.ls initial
+Initial guess for the center of the feature.
+.le
+.ls data[npts]
+Pixel data vector.
+.le
+.ls npts
+Number of points in the data vector.
+.le
+.ls width
+Width used to define the convolution function.  If the width is 1 or less
+then the nearest minimum or maximum is returned.  If the width is greater
+than 1 then a minimum with of 3 is used in the algorithm.
+.le
+.ls type
+Type of feature.  The feature types are defined in the file <xtools/center1d.h>.
+Currently the types are emission and absorption features.
+.le
+.ls radius
+Centering radius or error limit about the initial guess.
+.le
+.ls threshold
+Minimum difference between the maximum and minimum pixel value in the
+region around the initial guess allowed for detecting a feature.  For
+data which is all positive and the type is emission then the
+threshold is also used as an absolute cutoff.
+.le
+.ih
+DESCRIPTION
+If the width is 1 or less then the nearest minimum or maximum is found.
+The centering radius is still applied as is the threshold.  If the width
+is greater than 1 then a minimum width of 3 is used in the algorithm.
+
+The one dimensional position of a feature is determined by solving the equation
+
+	(1)	integral {(I-I0) f(X-XC) dX} = 0
+
+where I is the intensity at position X, I0 is the continuum intensity, X is the
+pixel coordinate, and XC is the desired feature position.  Figure 1 shows
+the range of pixels used in determining the continuum intensity, the feature
+threshold, and solving the equation.
+
+.ks
+.nf
+		      Figure 1:  Data Feature Vector
+      +-----------------------------------------------------------+
+     -|                               *                           |
+     S|                              * *                          |
+      |                              * *                          |
+     t|                             *   **                        |
+      |                             *     *                       |
+     r|                            *       *                      |
+      |                           *        *                      |
+     e|                          *          *                     |
+      |                         *            *                    |
+     n|                      *                 *              *  *|
+      |                   *                       *  *  *  *      |
+     t|             *  *                                          |
+      |       *  *                                                |
+     h|    *                                                      |
+     -| *                                                         |
+      +---------+-----------------+---------------------+---------+
+     -B        -A                 0                     A         B
+
+			        X-XC
+
+	A = radius + 0.5 width		B = radius + 1.5 width
+.fi
+.ke
+
+The range -A to A is used to determine the continuum intensity and
+the strength of the feature.  For absorption features the continuum
+intensity is the maximum point in this range while for emission
+features the continuum is set to zero.  Admittedly these are not real
+measures of the continuum but they contain the fewest assumptions
+and are tolerant of nearby contaminating features.  The feature strength
+is the difference between the maximum and minimum values.  If the feature
+strength is less than the specified detection threshold then a value of
+INDEF is returned for the feature position.
+
+.ks
+The range -B to B includes the range of allowed feature positions plus the
+half-width of the feature.  This range is used in solving equation (1).
+The convolution function f(X-XC) is a sawtooth as shown in figure 2.
+For absorption features the negative of this function is used.
+
+.nf
+		           Figure 2:  f(X-XC)
+	        +-------------------+-------------------+
+	        |                   |     *             |
+	        |                   |   *   *           |
+	        |                   | *       *         |
+             0  +-*-*-*-*-----------*-----------*-*-*-*-+
+	        |         *       * |                   |
+	        |           *   *   |                   |
+	        |             *     |                   |
+	        +-------+-----------+-----------+-------+
+	            -width/2       0         width/2
+
+		                   X-XC
+.fi
+.ke
+
+The two figures graphically define the parameter \fIwidth\fR.  Generally
+it should be set to a value near the actual width of the emission or absorption
+feature.  If the width is too wide then the center will be affected by blending
+from nearby lines while if it is too narrow the accuracy of the centering is
+decreased.  The parameter \fBradius\fR determines how far from the initial
+estimate for XC the interactive solution of (1) may go.
+Equation (1) is solved iteratively starting with the initial position.
+When successive positions agree within 0.1% of a pixel the position is
+returned.  If the position wanders further than \fIradius\fR from the
+initial guess or outside of the data vector then the procedure returns
+the value INDEF.  If more than 100 iterations are required or the corrections
+per iteration exceed the minimum correction reached after 3 further iterations
+then the solution has failed to converge and INDEF is returned.  Note that
+this latter condition may occur if the width is too small in a flat topped
+profile.
+
+This task uses the one dimensional image interpolation package \fBiminterp\fR
+in solving equation (1).
+.ih
+BUGS
+Though the algorithm does not fail if the width is made very small the
+results become unreliable.  Therefore a silent limit of 3 is imposed
+by the algorithm.  If there is ever a need to allow smaller widths
+then the procedure can be changed and the applications relinked.
+.endhelp
diff --git a/pkg/xtools/doc/cogetr.hlp b/pkg/xtools/doc/cogetr.hlp
new file mode 100644
index 00000000..416935c9
--- /dev/null
+++ b/pkg/xtools/doc/cogetr.hlp
@@ -0,0 +1,88 @@
+.help cogetr.hlp Feb86 xtools
+.ih
+NAME
+.nf
+comap   -- Initialize buffered image column access
+cogetr  -- Get buffered image columns from 2D image
+counmap -- Free memory used in image column access
+.fi
+.ih
+SYNOPSIS
+.nf
+pointer	im		# IMIO pointer
+pointer	co		# COGETR pointer
+int	maxbuf		# Maximum buffer size
+int	col		# Column
+int	line1		# First image line of column vector
+int	line2		# Last image line of column vector
+pointer	buf		# Returned pointer
+
+pointer	immap()		# Map the image
+pointer	comap()		# Map the column access
+pointer	cogetr()	# Get columns
+
+	im = immap (image, mode, 0)
+	co = comap (im, maxbuf)
+	buf = cogetr (co, col, line1, line2)
+	call counmap (co)
+.fi
+.ih
+DESCRIPTION
+A pointer to a real image column vector between the limits \fIline1\fR
+and \fIline2\fR is returned.  Internally the image data is buffered as
+a scrolled two dimensional section to minimize the number of image
+reads.  This interface is designed to be efficient when:
+
+.nf
+(1) The columns are accessed sequentially.
+(2) The number of lines does not change.
+(3) The first and last lines change slowly with the column accessed.
+.fi
+
+The column access interface is initialized with the procedure
+\fBcomap\fR.  At this time the maximum size of the internal buffer is
+set.  The buffer should be reasonably large.
+
+When the first column
+access is made with \fBcogetr\fR a buffer is created containing the
+number of lines requested and as many columns as will fit within the
+maximum buffer size.  When the number of lines is small then the number
+of columns buffered will be large (as large as the image if possible).
+When the number of lines is large then the columns may be buffered in
+blocks across the image.  A pointer to the real column vector requested is
+returned.  Subsequent calls to \fBcogetr\fR will return columns from the
+buffer without reading the image until a new buffer is required
+provided that the line limits do not change.  If the columns are
+accessed sequentially (usually from the first column to
+the last column) then the image will be accessed a minimum number of
+times consistent with the buffer size.
+
+One type of application accesses entire columns from the image
+so that the first and last lines do not change.  Another type allows
+the line limits to change in such a way that the total number of lines
+does not change and the changes are only a few lines between calls.
+In this case only the new lines are added to the scrolled buffer
+without the entire buffer needing to be filled.
+Applications of this type occur when following a feature across an
+image such as objects in long slit spectra or echelle orders.
+
+The buffer is created and initialized when the buffer pointer
+is null or when the number of lines requested is changed.  Both the
+buffer and the column data pointer are allocated by \fBcogetr\fR.
+The user must free the buffers with the procedure \fBcounmap\fR.
+.ih
+RETURNED VALUES
+\fBComap\fR returns a pointer to a structure internal to the interface.
+\fBCogetr\fR returns a pointer to a real vector containing the requested
+image column.
+.ih
+TIMINGS
+When used in applications requiring sequential column access with
+the line limits changing slowly or not at all this interface provides
+access nearly as efficiently as accessing lines.  The actual difference
+with the same application applied to lines depends on the number of
+buffer reads required (i.e. on the size of the image).
+.ih
+SEE ALSO
+xtsums
+.endhelp
diff --git a/pkg/xtools/doc/extrema.hlp b/pkg/xtools/doc/extrema.hlp
new file mode 100644
index 00000000..cea82502
--- /dev/null
+++ b/pkg/xtools/doc/extrema.hlp
@@ -0,0 +1,27 @@
+.help extrema Dec83 xtools
+.ih
+NAME
+extrema -- find the extrema in an array of x and y points
+.ih
+SYNOPSIS
+.nf
+nextrema = extrema (x, y, curvature, npts, dx)
+
+real	x[npts], y[npts]	# Input data points and output extrema
+real	curvature[npts]		# 2nd deriv. of cubic spline at extrema
+int	npts			# Number of input data points
+real	dx			# Precision of extrema positions
+.fi
+.ih
+DESCRIPTION
+The input data points are fitted with a cubic interpolation spline.  The
+spline is then searched for points where the first derivative changes sign.
+The minimum step size of this search is controlled by the parameter dx.
+The positions of these extrema are returned in the x array, the value of the
+spline at the extrema are returned in the y array, and the curvature or
+second derivative of the spline at the extrema are returned in the
+curvature array.  The function returns the number of extrema found.
+.ih
+SEE ALSO
+xtools.peaks
+.endhelp
diff --git a/pkg/xtools/doc/inlfit.hlp b/pkg/xtools/doc/inlfit.hlp
new file mode 100644
index 00000000..db256302
--- /dev/null
+++ b/pkg/xtools/doc/inlfit.hlp
@@ -0,0 +1,259 @@
+.help inlfit Aug91 xtools
+.ih
+NAME
+inlfit -- The interactive non-linear least squares fitting package
+
+.ih
+SYNOPSIS
+
+The INLFIT package is a set of procedures, callable from any IRAF task,
+for interactively fitting an arbitrary function of n independent variables
+using non-linear least squares techniques.  The calling task
+must supply the function to be fit and its derivatives, initial values for
+various convergence and bad data rejection parameters, the data to be fit,
+and weights for all the data points. The INLFIT package is layered on the
+NLFIT package which does the actual fitting.
+
+.ih
+DESCRIPTION
+
+INLFIT fits an n-dimensional function to a set of data
+points iterating until the reduced chi-squared changes
+by less than \fItolerance\fR percent between successive iterations, or
+until machine precision is reached, or until
+the maximum number
+of iterations \fImaxiter\fR is reached.  If the maximum number
+of iterations is reached before convergence a status flag
+is set.
+
+After computing an initial fit, INLFIT presents the user with a plot of
+the fit and activates the graphics cursor.
+At this point the user may examine and/or interact with the fit by,
+for example, reprogramming the default graph keys,
+editing the default convergence or bad data rejection parameters,
+deleting and undeleting points, 
+altering which parameters in the fitting function are actually to be
+fit and which are to be held constant, and refitting the data.
+
+If \fInreject\fR is greater than zero the RMS of the residuals is computed
+and points whose residuals are less than \fIlow_reject\fR * RMS
+or greater than \fIhigh_reject\fR * RMS value are excluded from the fit.
+Points within
+a distance \fIgrow\fR of a rejected point are also excluded from
+the fit. The function is then refit without the rejected points.
+The rejection algorithm is executed until the number of rejection
+iterations reaches \fInreject\fR or no more points are rejected.
+
+.ih
+CURSOR COMMANDS
+
+The following interactive cursor keystroke commands are available from
+within the INLFIT package.
+.ls ?
+The terminal is cleared and a menu of cursor keystroke and colon commands
+is printed.
+.le
+.ls c
+The id, coordinates of the data point nearest the cursor, along with the
+function value, the fitted value and the residual, are printed on the status
+line.
+.le
+.ls d
+The data point nearest the cursor and not previously deleted is marked with an
+X. It will not be used in further fits until it is undeleted.
+.le
+.ls f
+The function is fit to the data and the fit is graphed using the default
+plot type.
+.le
+.ls g
+Redefine the graph keys "h-l" from their defaults. A prompt is issued for the
+graph key to be redefined. Another prompt is issued for the data to be
+plotted at which point the user must enter the x and y axis data to plot,
+delimited by a comma. The data types are the following (they can be
+abbreviated to up to three characters).
+.nf
+
+    function    Dependent variable or function
+    fit         Fitted value
+    residuals   Residuals (function - fit)
+    ratio       Ratio (function / fit)
+    nonlinear   Nonlinear component
+    identifier  Independent variable named "identifier" (if defined)
+    var n       Independent variable number "n"
+    user n      User defined plot equation "n"  (if defined)
+
+.fi
+The application program can define independent variable names and user plot 
+functions, aside from the standard options provided. If variable names are 
+supplied, the user can reference them by their names. Otherwise they can be 
+always referenced by "var n", where "n" is the variable number (the user has 
+to know the variable order in this case). The ":variables" command will
+list the currently defined variables by name and number.
+The application program may
+define any number of plot equations aside from the defaults provided. In this 
+case the user may reference them by "user n", where "n" is the plot function 
+number (the user must know the equation order in this case). 
+.le
+.ls h, i, j, k, l
+By default each key produces a different graph. The graphs are described by
+the data which is graphed along each axis as defined above. The default graph
+keys,
+which may be redefined by the application program or interactively by using 
+the 'g' key, are the following.
+.nf
+
+        h       function, fit
+        i       function, residuals
+        j       function, ratio
+        k       var 1, function
+        l       user 1, user 2 (default)
+
+.fi
+The initial graph key, if not redefined by the application program is 'h'.
+.le
+.ls o
+Overplot the next fit provided the graph format has not changed.
+.le
+.ls q
+Exit from the interactive curve fitting package.
+.le
+.ls r
+Redraw the current graph.
+.le
+.ls t
+Toggle fit overploting on and off. If this option is on the data
+and fitted values are overplotted. Otherwise only data points are plotted.
+The fitted values are marked using boxes.
+.le
+.ls u
+Undelete the data point nearest the cursor which has been previously deleted.
+This option does not work over points marked as deleted by the application
+program before calling inlfit.
+.le
+.ls w [key]
+Set the graph window or data range along each axis to be graphed.. This is a 
+\fBgtools\fR option which prints the prompt "window:". The available cursor
+keystroke commands are printed with '?' and on-line help is available by
+typing "help gtools".
+.le
+.ls I
+Interrupt the task immediately without saving the current fit.
+.le
+
+Colon commands are used to show or set the values of parameters.
+The application program calling \fBinlfit\fR can add more commands.
+Parameter names can be abbreviated. The following commands are supported. 
+.ls :show [file]
+Show the current values of the fitting parameters high_reject, 
+low_reject, niterate, grow, tol, itmax. The default output device
+is the terminal (STDOUT) and the screen is cleared before the information
+is output. If a file is specified then the information is appended
+to the named file.
+.le
+.ls :variables [file]
+List the currently loaded variables. The number, id, minimum value and maximum
+value of each variable is printed. The default output device is the terminal
+(STDOUT) and the screen is cleared before the information is output.
+If a file is specified then the information is appended to the named file.
+.le
+.ls :data [file]
+List the raw data. The value of each standard catalog and observations
+catalog variable  for each data point is printed. The default output device
+is the terminal (STDOUT) and the screen is cleared before the information
+is output.  If a file is specified then the information is appended to
+the named file.
+.le
+.ls :errors [file]
+Show the error analysis of the current fit.  The number of iterations,
+total number of points,
+the number of rejected and deleted points, the standard deviation,
+the reduced chi, the average error (always = 1.0 if weight=1.0, otherwise
+= 1.0 / <weight>), the average scatter (always 0.0 if no weights scatter term is
+fit),
+the reduce chi, and the rms are printed on the screen. The fitted parameters
+and their errors are also printed. The default output is the terminal
+(STDOUT) and the screen is cleared before the information is
+output. If a file is specified then the information is appended to
+the named file.
+.le
+.ls :results [file]
+List the results of the current fit. The function value, the fitted value,
+the residual, and the weight are printed for each data point. The default
+output device is the terminal (STDOUT) and the screen is cleared before
+the information is output. If a file is specified then the information is
+appended to the named file.
+.le
+.ls :vshow [file]
+A verbose version of ":show" which is equivalent to a ":show" plus a ":errors"
+plus a ":results". The default output device is the terminal (STDOUT)
+and the screen is cleared before the information is output.
+If a file is specified then the information is appended to the named file.
+.le
+.ls :page file
+Page through the named file.
+.le
+.ls :tolerance [value]
+Show or set the value of the fitting tolerance. Tolerance is the maximum
+fraction by which the reduced chi-squared can change from one iteration to the
+next for the fit to meet the convergence criteria.
+.le
+.ls :maxiter [value]
+Show or set the maximum number of fitting iterations.
+.le
+.ls :nreject [value]
+Show or set the maximum number of rejection iterations. A value of zero
+means that automatic bad data rejection is turned off. 
+.le
+.ls :low_reject [value], :high_reject [value]
+Show or set the values of the bad data rejection limits.
+If both low_reject and high_reject are zero then automatic bad data
+rejection is turned off.
+If either of the high or low rejection limits are greater than zero,
+and nreject is greater than zero, the rms of the initial fit is computed.
+Points with residuals
+more than low_reject * rms below zero and high_reject * rms above zero
+are removed before the final fit. Rejected points are marked on the 
+graphs with diamonds. 
+.le
+.ls :grow [value]
+Show or set the value of the rejection growing radius. Any points
+within this distance of a rejected point are also rejected. 
+.le
+.ls :fit [parameter] [value]
+Set the starting guess value for the named coefficient and allow the 
+parameter value to change (converge) during the fit.
+If the value is not specified inlfit will use the last starting guess.
+.le
+.ls :const [parameter] [value]
+Set the named parameter to be a constant with the specified value, i.e,
+its value won't change during the fit.
+If the value is not specified inlfit will use its last starting value.
+.le
+.ls :/help
+Print help for the graph formatting options.
+.le
+.ls :.help
+Print help for the general IRAF graphics options.
+.le
+
+.ih
+ALGORITHMS
+
+INLFIT uses the standard Levenberg-Marquardt non-linear least squares
+algorithm to fit the data. Detailed descriptions of the algorithm can
+be found in the following two references.
+.nf
+
+1. Bevington, P.R., 1969, Data Reduction and Error Analysis for the
+   Physical Sciences, Chapter 11, page 235.
+
+2. Press, W.H. et al., 1986, Numerical Recipes: The Art of Scientific
+   Computing, Chapter 14, page 523.
+
+.fi
+
+.ih
+SEE ALSO
+icfit,gtools
+.endhelp
diff --git a/pkg/xtools/doc/peaks.hlp b/pkg/xtools/doc/peaks.hlp
new file mode 100644
index 00000000..dc9eb763
--- /dev/null
+++ b/pkg/xtools/doc/peaks.hlp
@@ -0,0 +1,28 @@
+.help peaks Jan84 xtools
+.ih
+NAME
+peaks -- find the peaks in an array of x and y points
+.ih
+SYNOPSIS
+.nf
+npeaks = peaks (x, y, background, npts, dx)
+
+real	x[npts], y[npts]	# Input data points and output peaks
+real	background[npts]	# Background estimate
+int	npts			# Number of input data points
+real	dx			# Precision of peak positions
+.fi
+.ih
+DESCRIPTION
+The extrema in the input data points are found using extrema(xtools).
+The extrema are located to a precision of dx.
+The extrema with negative curvature (peaks) are selected and returned
+in the x array.  The spline value is returned in the y array.  The
+background is estimated by linear interpolation of the neighboring
+minima (extrema of positive curvature) to the position of the peak.
+The background is returned in the background array.  The number of
+peaks found is returned as the function value.
+.ih
+SEE ALSO
+xtools.extrema
+.endhelp
diff --git a/pkg/xtools/doc/ranges.hlp b/pkg/xtools/doc/ranges.hlp
new file mode 100644
index 00000000..8f924698
--- /dev/null
+++ b/pkg/xtools/doc/ranges.hlp
@@ -0,0 +1,105 @@
+.help ranges Jan84 xtools
+.ih
+PURPOSE
+These tools
+parse a string using a syntax to represent integer values, ranges, and
+steps.   The parsed string is used to generate a list of integers for various
+purposes such as specifying lines or columns in an image or tape file numbers.
+.ih
+SYNTAX
+The syntax for the range string consists of non-negative integers, '-' (minus),
+'x', ',' (comma), and whitespace.  The commas and whitespace are ignored
+and may be freely used for clarity.  The remainder of the string consists
+of sequences of five fields.  The first field is the beginning of a range,
+the second is a '-', the third is the end of the range, the fourth is
+a 'x', and the fifth is a step size.  Any of the five fields may be
+missing causing various default actions.  The defaults are illustrated in
+the following table.
+
+.nf
+-3x1	A missing starting value defaults to 1.
+2-x1	A missing ending value defaults to MAX_INT.
+2x1	A missing ending value defaults to MAX_INT.
+2-4	A missing step defaults to 1.
+4	A missing ending value and step defaults to an ending
+	value equal to the starting value and a step of 1.
+x2	Missing starting and ending values defaults to
+	the range 1 to MAX_INT with the specified step.
+""	The null string is equivalent to "1 - MAX_INT x 1",
+	i.e all positive integers.
+.fi
+
+The specification of several ranges yields the union of the ranges.
+Note that the default starting value is 1 though one may specify zero
+as a range limit.
+.ih
+EXAMPLES
+The following examples further illustrate the range syntax.
+
+.nf
+-	All positive integers.
+1,5,9	A list of integers equivalent to 1-1x1,5-5x1,9-9x1.
+x2	Every second positive integer starting with 1.
+2x3	Every third positive integer starting with 2.
+-10	All integers between 1 and 10.
+5-	All integers greater than or equal to 5.
+9-3x1	The integers 3,6,9.
+.fi
+.ih
+PROCEDURES
+
+.ls 4 decode_ranges
+
+.nf
+int procedure decode_ranges (range_string, ranges, max_ranges, nvalues)
+
+char	range_string[ARB]	# Range string to be decoded
+int	ranges[3, max_ranges]	# Range array
+int	max_ranges		# Maximum number of ranges
+int	nvalues			# The number of values in the ranges
+.fi
+
+The range string is decoded into an integer array of maximum dimension
+3 * max_ranges.  Each range consists of three consecutive integers
+corresponding to the starting and ending points of the range and the
+step size.  The number of integers covered by the ranges is returned
+as nvalue.  The end of the set of ranges is marked by a NULL.
+The returned status is either ERR or OK.
+.le
+.ls 4 get_next_number, get_last_number
+
+.nf
+int procedure get_next_number (ranges, number)
+int procedure get_previous_number (ranges, number)
+
+int	ranges[ARB]		# Range array
+int	number			# Both input and output parameter
+.fi
+
+Given a value for number the procedures find the next (previous) number in
+increasing (decreasing)
+value within the set of ranges.  The next (previous) number is returned in
+the number argument.  A returned status is either OK or EOF.
+EOF indicates that there are no greater values.  The usual usage would
+be in a loop of the form:
+
+.nf
+	number = 0
+	while (get_next_number (ranges, number) != EOF) {
+	    <Statements using number>
+	}
+.fi
+.le
+.ls 4 is_in_range
+
+.nf
+bool procedure is_in_range (ranges, number)
+
+int	ranges[ARB]		# Ranges array
+int	number			# Number to check against ranges
+.fi
+
+A boolean value is returned indicating whether number is covered by
+the ranges.
+.le
+.endhelp
diff --git a/pkg/xtools/doc/xtextns.hlp b/pkg/xtools/doc/xtextns.hlp
new file mode 100644
index 00000000..f03f69ae
--- /dev/null
+++ b/pkg/xtools/doc/xtextns.hlp
@@ -0,0 +1,115 @@
+.help xt_extns Mar07 xtools
+.ih
+NAME
+.nf
+xt_extns -- Expand an MEF into a list of image extensions
+.fi
+.ih
+SYNOPSIS
+.nf
+int procedure xt_extns (files, index, extname, extver, lindex, lname, lver,
+	dataless, ikparams, err, imext)
+
+char	files[ARB]		#I List of MEF files
+char	index[ARB]		#I Range list of extension indexes
+char	extname[ARB]		#I Patterns for extension names
+char	extver[ARB]		#I Range list of extension versions
+int	lindex			#I List index number?
+int	lname			#I List extension name?
+int	lver			#I List extension version?
+int	dataless		#I Include dataless image headers?
+char	ikparams[ARB]		#I Image kernel parameters
+int	err			#I Print errors?
+int	imext			#O Image extensions?
+.fi
+.ih
+DESCRIPTION
+A list, \fIfiles\fR,  of regular images and multi-extension FITS (MEF)
+files is returned as a list of images.  In addition a flag, \fIimext\fR,
+is set indicating if image extensions are present.
+
+In order handle regular and MEF extension images in the same way one must
+understand that all images in IRAF may be addressed with a numeric index
+while those that are "regular" images may also be addressed without
+an index.  Non-FITS format images are considered to have an index of 1.
+For example, an image in the IRAF format may be addressed
+as pix.imh, pix, pix.imh[1], and pix[1].  FITS files start with index 0
+in order that index 1 may be used to refer to the first extension.
+So a plain FITS image, say foo.fits may also be addressed as foo, foo[0],
+or foo.fits[0].  If a FITS file has both a primary (index 0) image and
+extensions then the zero index must be explicitly used.
+
+For regular images the index range must include 0 for FITS images (or
+primary images in FITS files with extensions) and 1 for non-FITS images.
+In the resulting list, the index notation is dropped unless it is required;
+i.e. in a FITS file with both a primary image and extensions.
+
+The input set of candidate images may be filtered by index, extension
+name, extension version, and whether images are dataless.
+
+\fIindex\fR is a range list (see \fBranges\fR) of indices to be applied
+to each input file for identifying images.  If a null string is
+specified then all index values bet
+
+\fIindex\fR is a range list (see \fBranges\fR) of indices to be applied
+to each input file for identifying images.  If a null string is
+specified then all non-negative index values are examined.
+
+\fIextname\fR is a comma delimited list of patterns for extension names.
+If no list (a null string) or the string "*" is specified then no
+filtering on the extension name is done.  For a description of pattern
+matching syntax see \fBmatch\fR.  Extension names are those specified
+by the EXTNAME keyword.  For the purpose of explicit pattern matching
+strings a missing EXTNAME keyword is treated as the extension name "none".
+To include a comma in a pattern you must escape it by preceding it with
+'\', however, a comma in an extension name may cause other problems
+because IRAF image extension syntax using the extension name does not
+allow commas or whitespace.  Each pattern has '^' and '$' prepended
+and appended respectively which means the pattern must match the entire
+extension name.  A common mistake is that '*' in a pattern is different
+than '*' in a file template.  In this case use '?*'.
+
+The reasons for a list of patterns matching the entire extension name
+are to allow intuitive explicit lists of names, such as "im1,im11,im13",
+and to deal with names which are difficult to unambiguously specify with
+a single pattern.
+
+\fIextver\fR is a range list for extension version numbers.  If no
+list is given then no filtering on extension versions is performed.
+See \fBranges\fR for more on range lists.
+
+\fIdataless\fR is a boolean parameter that selects whether to filter out
+dataless images.  Dataless images are uncommon except for a class of MEF
+files where the primary image is used only for global inherited header
+keywords.  This parameter may be used to include this global header in
+expansions of this type of MEF files.
+
+The output of the list of selected images for FITS image extensions may
+be expressed either with the index notation (e.g. name[3]) or extension
+name and/or extension version (e.g. name[im3], name[im5,2]).  This is
+controlled by the \fIlindex\fR, \fIlname\fR and \fIlver\fR boolean
+parameters.  If the extension name and or version number are selected
+then that format is used even if \flindex\fR is also selected.  If
+there is no extension name or extension version then the index is used
+even if \fIlindex\fR is not selected.  Also remember that for regular
+images where an index or extension sections is not required none will
+be used.
+
+The output names may also include additional "image kernel" information.
+Different image types, currently mostly for FITS images, have parameters
+that may be specified in the image kernel section.  The \fIikparams\fR
+string may be used to add these additional parameters within the
+kernel section part of the name.
+
+Finally, the input files, including MEF files, in the input file list
+may include "image sections".  During processing image sections are
+stripped and then appended on the output.  For example, name[1:10,1:10]
+might expand to name[im1][1:10,1:10], name[im2][1:10,1:10], etc.
+
+\fIerr\fR may be used to print error messages when a particular image
+index fails to be opened.  Typically this would be to find nonexistent
+or read-protected images and files.
+.ih
+SEE ALSO
+mscextensions, imextensions, match, ranges
+.endhelp
diff --git a/pkg/xtools/doc/xtmaskname.hlp b/pkg/xtools/doc/xtmaskname.hlp
new file mode 100644
index 00000000..ddc8a07c
--- /dev/null
+++ b/pkg/xtools/doc/xtmaskname.hlp
@@ -0,0 +1,85 @@
+.help xt_maskname Mar07 xtools
+.ih
+NAME
+.nf
+xt_maskname -- create mask name 
+.fi
+.ih
+SYNOPSIS
+.nf
+procedure xt_maskname (fname, extname, mode, mname, maxchar)
+
+char	fname[ARB]			#I File name
+char	extname[ARB]			#I Default pixel mask extension name
+int	mode				#I Mode
+char	mname[maxchar]			#O Output mask name
+int	maxchar				#I Maximum characters in mask name
+.fi
+.ih
+DESCRIPTION
+This routine encapsulates creating a mask name from a user specified
+name, an optional extension name, and an optional environment variable.
+It checks if an explicit format is desired based on the presence of a
+".pl" extension for a pixel list file or the FITS kernel parameter
+"type=mask" (with the equal sign possibly escaped) for a FITS extension.
+If neither is specified then the default is a FITS extension unless the
+environment variable "masktype" is set to "pl".  If the application
+does not specify an extension name for FITS format the name "pl" is used.
+
+If the "masktype" environment variable is "pl" and the application requests
+an extension name then a directory with the specified filename is used (and
+created for a new mask) and the pixel list filename is the extension name.
+For example, if the filename is "obj1234" and the extension name is "im1"
+then the mask name is "obj1234/im1.pl".  As a fallback if a directory
+cannot be accessed the filename will have the form <fname>_<extname>.pl.
+
+Typically an application that specifically was designed to handle
+multi-extension FITS (MEF) files will use the same extension name for
+a mask as for the image extension to which it applies.
+.ih
+EXAMPLES
+1. When "masktype" is undefined and creating a new mask:
+
+.nf
+               fname extname		mname
+  --------------------------------------------------------
+                 abc ""         -->     abc[pl,type=mask]
+                 abc "def"      -->     abc[def,type=mask]
+  abc[def,type=mask] ""         -->     abc[def,type=mask]
+            abc[def] "ghi"      -->     abc[def,type=mask]
+              abc.pl ""         -->     abc.pl
+              abc.pl "def"      -->     abc.pl
+.fi
+
+2. When "masktype=pl" and creating a new mask:
+
+.nf
+               fname extname		mname
+  --------------------------------------------------------
+                 abc ""         -->     abc.pl
+                 abc "def"      -->     abc/def.pl
+  abc[def,type=mask] ""         -->     abc/def.pl
+            abc[def] "ghi"      -->     abc/def.pl
+              abc.pl ""         -->     abc.pl
+              abc.pl "def"      -->     abc.pl
+.fi
+
+3. When reading a mask it looks for either format unless an explicit
+".pl" extension is included.
+
+.nf
+               fname extname		mname
+  --------------------------------------------------------
+                 abc ""         -->     abc[pl]
+                 abc "def"      -->     abc[def]
+  abc[def,type=mask] ""         -->     abc[def,type=mask]
+            abc[def] "ghi"      -->     abc[def]
+              abc.pl ""         -->     abc.pl
+              abc.pl "def"      -->     abc.pl
+                 abc ""         -->     abc.pl
+                 abc "def"      -->     abc/def.pl
+            abc[def] ""         -->     abc/def.pl
+            abc[def] "ghi"      -->     abc/def.pl
+            abc[def] ""         -->     abc_def.pl
+.fi
+.endhelp
diff --git a/pkg/xtools/doc/xtools.hd b/pkg/xtools/doc/xtools.hd
new file mode 100644
index 00000000..38665086
--- /dev/null
+++ b/pkg/xtools/doc/xtools.hd
@@ -0,0 +1,45 @@
+# Help directory for the XTOOLS (programming tools) package.
+
+$xtools		= "pkg$xtools/"
+$fixpix		= "pkg$xtools/fixpix/"
+$icfit		= "pkg$xtools/icfit/"
+$gtools		= "pkg$xtools/gtools/"
+$ranges		= "pkg$xtools/ranges/"
+$skywcs		= "pkg$xtools/skywcs/doc/"
+$catquery	= "pkg$xtools/catquery/doc/"
+
+revisions	sys = xtools$Revisions
+dttext		hlp = xtools$dttext.x,		src = ..
+cogetr		hlp = cogetr.hlp,		src = xtools$cogetr.x
+comap		hlp = cogetr.hlp,		src = xtools$cogetr.x
+counmap		hlp = cogetr.hlp,		src = xtools$cogetr.x
+xt_extns	hlp = xtextns.hlp,		src = xtools$xtextns.x
+xt_lsum		hlp = xtsums.hlp,		src = xtools$xtsums.x
+xt_csum		hlp = xtsums.hlp,		src = xtools$xtsums.x
+xt_lsumb	hlp = xtsums.hlp,		src = xtools$xtsums.x
+xt_lsuml	hlp = xtsums.hlp,		src = xtools$xtsums.x
+xt_maskname	hlp = xtmaskname.hlp,		src = xtools$xtmaskname.x
+xt_pmmap	hlp = xtpmmap.hlp,		src = fixpix$xtpmmap.x
+clgsec		hlp = clgsec.hlp,		src = xtools$clgsec.x
+extrema		hlp = extrema.hlp,		src = xtools$extrema.x
+getdatatype	hlp = getdatatype.hlp,		src = xtools$getdatatype.x
+gstrdetab	hlp = gstrdetab.hlp,		src = xtools$gstrdetab.x
+gstrentab	hlp = gstrentab.hlp,		src = xtools$gstrentab.x
+gstrsettab	hlp = gstrsettab.hlp,		src = xtools$gstrsettab.x
+peaks		hlp = peaks.hlp,		src = xtools$peaks.x
+ranges		hlp = ranges.hlp,		src = xtools$ranges.x
+strdetab	hlp = strdetab.hlp,		src = xtools$strdetab.x
+strentab	hlp = strentab.hlp,		src = xtools$strentab.x
+center1d	hlp = center1d.hlp,		src = xtools$center1d.x
+icfit		hlp = icfit$icfit.hlp
+inlfit		hlp = xtools$doc/inlfit.hlp
+#gtools		hlp = gtools$gtools.hlp,	pkg = gtools$gtools.hd
+gtools		hlp = gtools$gtools.hlp
+
+skywcs		hlp = skywcs$skywcs.men,
+		sys = skywcs$skywcs.hlp,
+		pkg = skywcs$skywcs.hd
+
+catquery	hlp = catquery$catquery.men,
+		sys = catquery$catquery.hlp,
+		pkg = catquery$catquery.hd
diff --git a/pkg/xtools/doc/xtools.men b/pkg/xtools/doc/xtools.men
new file mode 100644
index 00000000..8fe85373
--- /dev/null
+++ b/pkg/xtools/doc/xtools.men
@@ -0,0 +1,23 @@
+       catquery - Catalog query package
+         clgsec - Get and decode an image section
+      clginterp - Get integer code for interpolator type
+         cogetr - Efficient image column access
+          comap - Map for column access procedure
+        counmap - Unmap for column access procedure
+	extrema - Find extrema in x and y data points
+    getdatatype - Convert type suffix character to TY_ type code
+      gstrdetab - Remove tabs from a string
+      gstrentab - Put tabs in a string where possible
+     gstrsettab - Set tab stops for gstrdetab, entab.
+	 gtools - Graphics tools
+	  icfit - Interactive curve fitting package
+	 inlfit - Interactive non-linear least squares fitting package
+	  peaks - Find peaks in x and y data points
+	 ranges - Parse a list of ranges "1,3,5-7,.."
+         skywcs - Celestial coordinates transformation package
+       strdetab - Simplified detab
+       strentab - Simplified entab
+        xt_csum - Sum of image columns using column access procedure
+       xt_csumb - Buffered sum of image columns using column access procedure
+        xt_lsum - Sum of image lines
+       xt_lsumb - Buffered sum of image lines for moving sums
diff --git a/pkg/xtools/doc/xtpmmap.hlp b/pkg/xtools/doc/xtpmmap.hlp
new file mode 100644
index 00000000..94752da3
--- /dev/null
+++ b/pkg/xtools/doc/xtpmmap.hlp
@@ -0,0 +1,144 @@
+.help xt_pmmap Mar07 xtools
+.ih
+NAME
+.nf
+xt_pmmap -- map a mask and match it to a reference image
+.fi
+.ih
+SYNOPSIS
+.nf
+# Open a mask.
+pointer procedure xt_pmmap (pmname, refim, mname, sz_mname)
+
+char	pmname[ARB]		#I Pixel mask name
+pointer	refim			#I Reference image pointer
+char	mname[ARB]		#O Expanded mask name
+int	sz_mname		#O Size of expanded mask name
+
+
+# Close the mask.
+procedure xt_pmunmap (im)
+
+pointer im                      #I IMIO pointer for mask
+.fi
+.ih
+DESCRIPTION
+This interface maps (opens) and unmaps (closes) a mask for use in an
+application.  It includes resolving mask files from image header keywords
+in a reference image, inverting masks, matching masks spatially to a
+reference image, and access to non-pixel list formats.
+
+The \fIpmname\fR argument is a file name or a reference to an image header
+keyword using the syntax "!<keyword>".  As a special case the name "BPM"
+is equivalent to "!BPM".  It is also legal for the file name to be a null
+string which returns a NULL pointer for the application to interpret
+as desired.  Most applications will treat this case as all image pixels
+are good.
+
+If the file name, or the file name obtained from a keyword reference,
+begins with the character '^' the mask will be inverted to a boolean mask.
+This means that input mask values which are zero are set to 1 and non-zero
+mask values are set to 0.
+
+The \fIrefim\fR argument is the IMIO image pointer for a reference image
+used to resolve keyword references and for spatial matching.
+
+The map routine returns the mask name through the \fImname\fR argument.
+Typically an application would use the mask name for logging purposes
+since it will expand keyword mask references.
+
+.sh
+SPATIAL MATCHING
+
+The matching of masks to a reference image is a powerful feature though it
+can also cause confusion.  The advantage of matching is that when images
+are modified by trimming or other linear geometric operations the mask,
+often referenced in the image header, will still correctly identify
+the bad pixels.  Note that this does not apply to non-linear coordinate
+transformations.
+
+The matching is based on a "physical" coordinate system.  This is typically
+the image pixel coordinate system prior to any linear transformation.
+IRAF tasks which extract subrasters, subsample, block average, block
+replicate, transpose, etc. update header keywords describing the mapping
+from the image pixel coordinate system (called the "logical" coordinate
+system) to the parent physical coordinate system.  Some applications
+also attach a meaning to the physical coordinate system such as detector
+array coordinates.
+
+The transformation between logical coordinates (lx,ly) and physical
+coordinates (px,py) is defined by the header keywords LTM1_1, LTM2_1,
+LTM1_2, LTM_2_2, LTV1, and LTV2 as shown below.
+
+.nf
+    lx = px * LTM1_1 + py * LTM2_1 + LTV1
+    ly = px * LTM1_2 + py * LTM2_2 + LTV2
+
+    px = ( LTM2_2 * (lx - LTV1) - LTM2_1 * (ly - LTV2)) /
+	 (LTM1_1 * LTM2_2 - LTM1_2 * LTM2_1)
+    py = (-LTM1_2 * (lx - LTV1) + LTM1_1 * (ly - LTV2)) /
+	 (LTM1_1 * LTM2_2 - LTM1_2 * LTM2_1)
+.fi
+
+Note that a missing keyword defaults to a value of zero.  When all
+LTM/LTV keywords are missing then the physical and logical coordinate
+systems are identical.  In other words the implied transformation is
+an identify transformation.  Note that one cannot just have
+LTV keywords because then the implied transformation matrix is
+ill-defined (all matrix elements are assumed zero).
+
+The matching consists of deriving a transformation between the
+logical pixels in the image and the mask by combining the two physical
+transformations.  This means that even if the logical to physical
+transformations are complex, such as a rotation, if the two are the same
+a identity or a simple offset relative transformation may still exist
+between the two.  In this combined logical-to-logical transformation
+the current version does not allow a rotation though, as just noted, the
+separate logical-to-pixel transformation may be rotated by the same amount.
+
+When the image is sampled more finely than the mask, that is the same mask
+pixel overlaps multiple image pixels, then the nearest mask value (pixel
+center to pixel center) is used for each image pixel.  When the image is
+more coarsely sampled, that is more than one mask pixel overlaps an image
+pixel, then the maximum mask value becomes the mask value for the pixel.
+This latter choice means that if an image pixel is touched by any bad
+pixel then it will be indicated as bad.
+
+If after matching the mask to the image the mask does not cover
+the image, the mask is extended by adding zero mask values.
+
+The above description is fairly general which makes this seem complex.
+However, by far the most common mismatch between an image and its mask
+is that an image has been derived as a subraster of a parent image.
+In this case the LTM values will be LTM1_1=LTM2_2=1 and LTM2_1=LTM1_2=0
+(or missing) and the matching just depends on the origin offset keywords
+LTV1 and LTV2.
+
+Note that to eliminate this matching one resets the physical coordinate
+system to be equivalent to the logical coordinate system.  The task
+\fIwcsreset\fR can be used or the above LTM/LTV keywords can be deleted
+using a header keyword editor.
+
+.sh
+ALTERNATIVE MASK DESCRIPTIONS
+
+This interface accepts alternate mask descriptions that are internally
+converted to the same mask structure for transparent use by the application.
+The preferred input mask description is a pixel mask in either pixel list
+format (.pl extension) or a FITS pixel mask (a binary table representation).
+The alternate representations are a regular image and a text description.
+
+The pixels values in a regular image are truncated (towards zero) to integers.
+Then negative values are set to 0.
+
+A text description consists of lines in a text file with either two or
+four values.  The values are truncated to integers if needed.  Two values
+define a mask value of 2 at the (x,y) coordinate.  Four values define a
+region, given as (x1,x2,y1,y2) of mask values.  The mask values are 2 if
+the width of the region is narrower or equal to the height.  Otherwise the
+value is 3.  This is a convention used by task which then interpolate
+across bad pixel regions.
+
+Note that a text description is always tied directly to the input
+image; that is, the physical and logical coordinate systems are the same.
+.endhelp
diff --git a/pkg/xtools/doc/xtsums.hlp b/pkg/xtools/doc/xtsums.hlp
new file mode 100644
index 00000000..c91ef644
--- /dev/null
+++ b/pkg/xtools/doc/xtsums.hlp
@@ -0,0 +1,83 @@
+.help xtsums Feb86 xtools
+.ih
+NAME
+.nf
+xt_lsum  -- Sum image lines
+xt_csum  -- Sum image columns
+xt_lsumb -- Sum image lines with buffering
+xt_csumb -- Sum image columns with buffering
+.fi
+.ih
+SYNOPSIS
+.nf
+pointer	im		# IMIO pointer
+pointer	co		# COGETR pointer
+int	col1, col2	# Column limits of the sum
+int	line1, line2	# Line limits
+pointer	data		# Data pointer returned
+
+	call xt_lsum (im, col1, col2, line1, line2, data)
+	call xt_csum (co, col1, col2, line1, line2, data)
+	call xt_lsumb (im, col1, col2, line1, line2, data)
+	call xt_csumb (co, col1, col2, line1, line2, data)
+.fi
+.ih
+DESCRIPTION
+The specified lines or columns in a 2D images are summed and a pointer to
+the real sum vector is returned.  For \fBxt_lsum\fR and \fBxt_lsumb\fR the
+lines between \fIline1\fR and \fIline2\fR are summed and a pointer to the summed
+vector between \fIcol1\fR and \fIcol2\fR is returned.  Similarly, for
+\fBxt_csum\fR and \fBxt_csumb\fR the columns between \fIcol1\fR and \fIcol2\fR
+are summed and a pointer to the summed vector between \fIline1\fR and
+\fIline2\fR is returned.  The data pointer is to a real vector.  The column
+sums use the efficient column access procedures described in \fBcogetr\fR.
+
+The procedures without the 'b' suffix read the set of lines or columns
+in the sum from the image every time.  The 'b' suffix procedures buffer
+the lines or columns such that if only a few lines or columns are different
+from the preceding sum then only those lines or columns are read.  Thus the
+"buffered" sums are used for moving sums while the unbuffered procedures are
+used when there is no overlap between the sums.
+.ih
+RETURN VALUE
+The returned pointer \fIdata\fR is to a vector of type real.
+.ih
+EXAMPLES
+Suppose a sum of "nsum" lines or columns is required through the image
+in steps of "nstep".  The following code fragment illustrates the usage.
+
+.nf
+	im = immap (image, READ_ONLY, 0)
+	switch (axis) {
+	case 1:
+	    col1 = 1
+	    col2 = IM_LEN(im, 1)
+	    for i = 1, IM_LEN(im, 2), nstep {
+	        if (nstep < nsum)
+		    call xt_lsumb (co, col1, col2, i, i+nsum-1, data)
+	        else
+		    call xt_lsum (co, i, i+nsum-1, line1, line2, data)
+
+	        # Do operations on vector Memr[data]
+	    }
+	case 2:
+	    co = comap (im, maxbuf)
+
+	    line1 = 1
+	    line2 = IM_LEN(im, 2)
+	    for i = 1, IM_LEN(im, 1), nstep {
+	        if (nstep < nsum)
+		    call xt_csumb (co, i, i+nsum-1, line1, line2, data)
+	        else
+		    call xt_csum (co, i, i+nsum-1, line1, line2, data)
+
+	        # Do operations on vector Memr[data]
+	    }
+	    call counmap (co)
+	}
+	call imunmap (im)
+.fi
+.ih
+SEE ALSO
+cogetr
+.endhelp