Initial commit

6 files changed, 567 insertions, 0 deletions

diff --git a/pkg/utilities/nttools/threed/doc/selectors.hlp b/pkg/utilities/nttools/threed/doc/selectors.hlp
new file mode 100644
index 00000000..fd5390a7
--- /dev/null
+++ b/pkg/utilities/nttools/threed/doc/selectors.hlp
@@ -0,0 +1,91 @@
+.help selectors Nov96 tables
+.ih
+NAME
+selectors -- Table row/column selector syntax.
+.ih
+BASIC SYNTAX
+Selectors are appended to table names using a bracket notation. The
+construct "[c:......]" appended to a table name tells that a column
+selector exists. In a similar way, the construct "[r:......]" indicates
+a row selector.
+.ih
+COLUMN SELECTOR
+The basic structure of a column selector is a list of column patterns 
+separated by commas. The column pattern is either a column name, a file 
+name containing a list of column names, or a pattern using the usual IRAF 
+pattern matching syntax. For example, the string
+.nf
+	[c:a[1-9], b, time*, @column.lis]
+.fi
+
+would be expanded as the column names a1 through a9, b, any column
+name beginning with "time", and all the column names in the file
+column.lis. If the column list is entirely whitespace, all columns are
+selected. If the first non-white character is the negation character (~), 
+the selected columns will include all columns not matched by the list. 
+The negation character only has this meaning at the beginning of the list.
+.ih
+ROW SELECTOR
+Rows are selected according to a qpoe filter. The filter is evaluated
+at each table row, and the row is selected if the filter is true.
+
+For sake of an example, suppose we have a star catalog with the
+columns Name, Ra, Dec, V, B-V, and U-B. The simplest sort of filter is
+the equality test. The name of the column appears on the left of an
+equals sign and the column value appears on the right. For example,
+[name=eta_uma]. (The brackets in this and the following example are
+not actually part of the filter.)  Column numbers can be used in place
+of the column name.  This is especially useful for ascii
+tables. Values can be either numbers or strings. It is usually not
+necessary to place strings in quotes.  However, any string (including
+a column name) contains embedded blanks or characters significant to
+the qpoe filter, such a equal signs, commas, or colons, it should be
+placed in quotes.
+
+Ranges of values can be specified by giving the endpoints of the
+ranges separated by a colon. For example, [r:v=10:15] selects all rows
+with visual magnitude between 10 and 15.  Ranges include their
+endpoints. Ranges can also be used with strings as well as
+numbers. Ranges can also be one sided. The filter [r:dec=80:] selects
+all rows with declination greater than or equal to eighty degress and
+the filter [r:dec=:-40] selects all declinations less than or equal to
+forty degrees south. A filter can contain a list of single values and
+ranges. The values in the list should be enclosed in parentheses. For
+example, [r:name=(eta_uma,alpha_lyr)] or [r:b-v=(-1:0,0.5:1)]. 
+
+Individual values or ranges can be negated by placing a ! in front of
+them. For example, [r:name=!eta_uma] selects every row except the star
+named eta_uma and [r:ra=!0:6] selects all rows except those with right
+ascension between zero and six hours. An entire list can be negated by
+placing a ! in front of the column name or the parentheses enclosing
+the list. The filters [r:!name=(eta_uma,alpha_lyr)] and
+[r:name=!(eta_uma,alpha_lyr)] and [r:name=(!eta_uma,!alpha_lyr)] are all
+equivalent.
+
+Filters can test more than one column in a table. The individual tests
+are separated by commas or semicolons. All tests in the filter must
+succeed for the filter to be accepted. For example,
+[r:ra=1.3:1.4,dec=40:42] selects a rectangular region in the catalog. A
+range of row numbers can also be selected by placing the word row on
+the left side of the equals sign. For example, [r:row=10:20] selects
+rows from ten to twenty inclusive and [r:row=50:] selects all rows from
+fifty on. Row selection can be combined with any other test in a
+filter.  A filter, can also be placed in an include file, for example
+[r:@filter.lis]. Include files can be a part of a larger expression 
+and include files can contain other files, up to seven levels deep.
+.ih
+EXAMPLES
+.nf
+1. "[c:WAVELENGTH,FLUX]"        selects columns named "WAVELENGTH" and 
+                                "FLUX"
+
+2. "[r:WAVELENGTH=(4000:5000)]" selects all rows in which the WAVELENGTH
+                                column assumes values in between 4000 and 
+                                5000.
+
+3. "[c:FLUX][r:row=(25:30)]"    selects column FLUX and all rows from 25 
+                                to 30.
+.fi
+.ih
+SEE ALSO
+.endhelp
diff --git a/pkg/utilities/nttools/threed/doc/tiimage.hlp b/pkg/utilities/nttools/threed/doc/tiimage.hlp
new file mode 100644
index 00000000..1319d2e0
--- /dev/null
+++ b/pkg/utilities/nttools/threed/doc/tiimage.hlp
@@ -0,0 +1,108 @@
+.help tiimage Jan97 tables
+.ih
+NAME
+tiimage -- Inserts images into rows of a 3-D table.
+.ih
+USAGE
+tiimage input outtable
+.ih
+DESCRIPTION
+This task performs the inverse operation of task tximage: it inserts one or 
+more images into rows of a 3-D table  The input may be a filename template, 
+including wildcard characters, or the name of a file (preceded by an @ sign) 
+containing image names.  The output is a single 3-D table name.
+Each image in the input list is inserted as an array into a single cell at 
+the specified row in the output table. Any dimensionality information existent
+in the input image is lost in the process, that is, the image will be always
+inserted as a 1-D array, regardless of its number of axis.
+
+If the output table exists, insertion will be done in place. Alternatively, 
+the task can create a 3-D table from information taken either from a template 
+3-D table, or, if this table is not supplied, from the input images themselves. 
+This task supports a column selector in table names. This selector may be 
+used to select a single column in the table. If no selector is used, all 
+columns will be processed. Type 'help selectors' to see a description of 
+the selector syntax. 
+
+If the output table exists, insertion may take place in two ways. If the
+output table name contains a column selector that selects a single column
+in the table, all input images will be inserted in that column, starting
+at the row pointed by task parameter "row". 
+If "row" is negative or INDEF the task will look for the ORIG_ROW
+keyword in the image header and use that keyword value for row number.
+The second mode of insertion in an existing table is used if no matching
+column selector is found in the output table name. In this case the task
+will look for the columnar information written in the input image header by 
+task tximage, and use that information to place the image in the proper 
+column. If no columnar information exists in the header, or if the column 
+name in there does not match any column in the output table, the image is 
+skipped and the user warned. The "row" parameter processing works the same 
+way in this second mode.
+
+If the output table does not exist, the task will look for a template table
+where to take column information from. If the template exists, the insertion
+operation will be performed in an analogous way as above. Notice that the
+result may be a single-column table if the template has a valid (matching)
+column selector in its name, or a sparse table if not, because only the 
+actual input images will be stored in an otherwise empty table (the template 
+data is not copied into the output, only the column descriptors).
+
+If the template is missing, the task will attempt to retrieve columnar
+information from the input image headers and build the output table with
+enough columns and rows to fit all images in the list. Only images that
+have columnar information in their headers can be processed, though. If
+no images are found with the proper header keywords, no output takes place.
+
+NOTE: Both the output and template table names must always be supplied 
+complete, including their extension. Otherwise the task may get confused 
+on the existence of an already existing table.
+
+The column matching criterion is based on the column name. An error results 
+when data types in input image and output column do not agree.
+
+If the maximum array size in a target column in the output 3-D table is
+larger than the number of pixels in the input image, the array will be filled 
+up starting from its first element, and the empty elements at the end will 
+be set to INDEF. If the maximum array size is smaller than the number of 
+pixels, insertion begins by the first pixel up to the maximum allowable size, 
+the remaining pixels being ignored.
+.ih
+PARAMETERS
+.ls input [image name list/template]
+A list of one or more images to be inserted.
+.le
+.ls outtable [table name]
+Name of 3-D output table, including extension. No support exists for 
+"STDOUT" (ASCII output).
+.le
+.ls (template = "") [table name]
+Name of 3-D table to be used as template when creating a new output table.
+.le
+.ls (row = INDEF) [int]
+Row where insertion begins. If set to INDEF or a negative value, the row
+number will be looked for in the input image header.
+.le
+.ls (verbose = yes) [boolean]
+Display names as files are processed ?
+.le
+.ih
+EXAMPLES
+Insert images into a 3-D table at column named FLUX:
+
+.nf
+cl> tiimage flux*.hhh "otable.tab[c:FLUX]"
+.fi
+.ih
+BUGS
+The output and template table names must be supplied in full, including 
+the extension (e.g. ".tab"). If the output table name is not typed in full, 
+the task will create a new table in place of the existing one, with only 
+the rows actually inserted. This behavior relates to the way the underlying 
+"access" routine in IRAF's fio library works.
+.ih
+REFERENCES
+This task was written by I. Busko.
+.ih
+SEE ALSO
+tximage, selectors
+.endhelp
diff --git a/pkg/utilities/nttools/threed/doc/titable.hlp b/pkg/utilities/nttools/threed/doc/titable.hlp
new file mode 100644
index 00000000..f0479b6b
--- /dev/null
+++ b/pkg/utilities/nttools/threed/doc/titable.hlp
@@ -0,0 +1,100 @@
+.help titable Mar97 tables
+.ih
+NAME
+titable -- Inserts 2-D tables into rows of a 3-D table.
+.ih
+USAGE
+titable intable outtable
+.ih
+DESCRIPTION
+This task performs the inverse operation of task txtable: it inserts one or 
+more 2-D tables into rows of a 3-D table  The input may be a filename 
+template, including wildcard characters, or the name of a file (preceded by 
+an @ sign) containing table names.  The output is a single 3-D table name.
+If the output table exists, insertion will be done in place. If the output 
+table does not exist, it will be created. The input and output tables must 
+not be the same.
+
+This task supports row/column selectors in the input table names. These
+may be used to select subsets of both rows and columns from the input table.
+If no selectors are used, all columns and rows will be processed, 
+Type 'help selectors' to see a description of the selector syntax. 
+
+When creating a new output table, the information describing its columns
+can be taken from two sources. If parameter 'template' has the name of an
+existing 3-D table, the column descriptions, including maximum array sizes,
+will be taken from that table. If 'template' has an invalid or null ("")
+value, the column-defining information will be take from the first table 
+in the input list, where its number of rows will define the maximum array
+size allowed in the table being created. Column selectors are allowed in
+the template table.
+
+NOTE: Both the output and template table names must always be supplied 
+complete, including their extension. Otherwise the task may get confused 
+on the existence of an already existing table.
+
+Insertion is performed by first verifying if column names in both input
+and output tables match. If a match is found, values taken from that column
+and all selected rows from the input table will be stored as a 1-dimensional 
+array in a single cell in the corresponding column in the output 3-D table. 
+The row in this table where the insertion takes place is selected by the 
+"row" task parameter. It points to the row where the first table in the input 
+list will be inserted, subsequent tables in the list will be inserted into 
+subsequent rows. This mechanism is superseded if the "row" parameter is set 
+to INDEF or a negative value, and the keyword "ORIG_ROW" is found in the 
+header of the input table. This keyword is created by task txtable and its 
+value supersedes the row counter in the task.
+
+If the maximum array size in a target column in the output 3-D table is
+larger than the number of selected input rows, the array will be filled 
+up starting from its first element, and the empty elements at the end will 
+be set to INDEF (or "" if it is a character string column). If the maximum 
+array size is smaller than the number of selected rows, insertion begins by
+the first selected row up to the maximum allowable size, the remaining rows
+being ignored.
+
+This task correctly handles scalars stored in the input table header
+by task txtable. Since the selector mechanism does not work with these
+scalars, the task will always insert them into the output table, provided
+there is a match in column names.
+.ih
+PARAMETERS
+.ls intable [file name list/template]
+A list of one or more tables to be inserted. Row/column selectors are supported.
+.le
+.ls outtable [table name]
+Name of 3-D output table, including extension. No support exists for 
+"STDOUT" (ASCII output).
+.le
+.ls (template = "") [table name]
+Name of 3-D table to be used as template when creating a new output table.
+.le
+.ls (row = INDEF) [int]
+Row where insertion begins. If set to INDEF or a negative value, the row
+number will be looked for in the input table header.
+.le
+.ls (verbose = yes) [boolean]
+Display names of input and output tables as files are processed ?
+.le
+.ih
+EXAMPLES
+Insert columns named FLUX and WAVELENGTH from input tables into a 3-D table:
+
+.nf
+cl> titable "itable*.tab[c:FLUX,WAVELENGTH]" otable.tab
+.fi
+
+.ih
+BUGS
+The output and template table names must be supplied in full, including 
+the extension (e.g. ".tab"). If the output table name is not typed in full, 
+the task will create a new table in place of the existing one, with only the 
+rows actually inserted. This behavior relates to the way the underlying 
+"access" routine in IRAF's fio library works.
+.ih
+REFERENCES
+This task was written by I. Busko.
+.ih
+SEE ALSO
+txtable, selectors
+.endhelp
diff --git a/pkg/utilities/nttools/threed/doc/tscopy.hlp b/pkg/utilities/nttools/threed/doc/tscopy.hlp
new file mode 100644
index 00000000..144b483a
--- /dev/null
+++ b/pkg/utilities/nttools/threed/doc/tscopy.hlp
@@ -0,0 +1,94 @@
+.help tscopy Nov96 tables
+.ih
+NAME
+tscopy -- Copy tables.
+.ih
+USAGE
+tscopy intable outtable
+.ih
+DESCRIPTION
+This task is used to copy tables.  The input may be a filename
+template, including wildcard characters or the name of a file (preceded
+by an @ sign) containing table names.  The output may be either a directory
+specification or a list of table names.  If the output is a list of tables
+then there must be the same number of names in the input and output lists,
+and the names are taken in pairs, one from input and one from output.
+The input and output tables must not be the same.
+
+This task supports row/column selectors in the input table name. These
+may be used to select subsets of both rows and columns from the input table.
+Type 'help selectors' to see a description of the selector syntax. 
+
+NOTE: Be careful when using a wildcard for the extension.
+If you have the files 'table.tab' and 'table.lis' in the current directory,
+for example, then the command "tscopy tab* test/" would copy both files to the subdirectory
+'test'.
+.ih
+PARAMETERS
+.ls intable [file name template]
+A list of one or more tables to be copied. Row/column selectors are supported.
+.le
+.ls outtable [file name template]
+Either a directory name or a list of output table names. The standard
+value "STDOUT" generates ASCII output that can be redirected to a file.
+.le
+.ls (verbose = yes) [boolean]
+Display names of input and output tables as files are copied?
+.le
+.ih
+EXAMPLES
+1. To simply copy a table:
+
+.nf
+      cl> tscopy table tablecopy
+.fi
+
+2. To copy a table into an ASCII table:
+
+.nf
+      cl> tscopy table STDOUT > table.txt
+.fi
+
+3. To copy several tables:
+
+.nf
+      cl> tscopy table1,table2,tab67 a,b,c
+      cl> tscopy tab*.tab a,b,c
+.fi
+In the latter case the extension is given explicitly in case there
+are other files beginning with "tab" that are not tables; there must
+be exactly three tables beginning with "tab" because the output list
+has three names.
+
+4. To copy a set of tables to a new directory:
+
+.nf
+      cl> tscopy table*.tab directory
+			or
+      cl> tscopy table*.tab directory$
+			or
+      cl> tscopy table*.tab osdirectory
+.fi
+
+where "directory" is an IRAF environment variable for a directory name,
+and "osdirectory" is an operating system directory name
+(e.g., "/user/me/" in UNIX).
+
+5. To copy a subset of rows and columns:
+
+.nf
+      cl> tscopy "table.tab[c:wave,flux][r:wave=(4000:5000)]" tableout
+.fi
+
+This command will copy only columns named "wave" and "flux" from the input
+table to the output. It will also select and copy only the rows in which
+the "wave" value lies between 4000 and 5000.
+.ih
+BUGS
+.ih
+REFERENCES
+This task was written by Bernie Simon.
+.ih
+SEE ALSO
+selectors
+.endhelp
diff --git a/pkg/utilities/nttools/threed/doc/tximage.hlp b/pkg/utilities/nttools/threed/doc/tximage.hlp
new file mode 100644
index 00000000..9f331958
--- /dev/null
+++ b/pkg/utilities/nttools/threed/doc/tximage.hlp
@@ -0,0 +1,85 @@
+.help tximage Jan97 tables
+.ih
+NAME
+tximage -- Extract 1-D images from cells of a 3-D table.
+.ih
+USAGE
+tximage intable output
+.ih
+DESCRIPTION
+This task extracts one or more 1-D images from cells of a 3-D table.
+The input may be a filename template, including wildcard characters, 
+or the name of a file (preceded by an @ sign) containing table names. 
+The output may be either a directory specification or a list of image names. 
+If the output is a list of images then there must be the same number of names 
+in the input and output lists, and the names are taken in pairs, one from 
+input and one from output.
+
+Images can be extracted only from a single column in the input table.
+That column must be designated by an appropriate column selector appended to 
+the table name. Type 'help selectors' to get more information on row/column 
+selector syntax.
+
+Row selectors may be used to select subsets of rows from the input table.
+If no row selector is used, all rows will be extracted, and the number
+of output images will be the number of rows in the input table.
+
+Since one input table may generate several output images, the task adopts
+the following naming scheme for these output images: their names are
+built by appending a suffix to the name given in parameter "output".
+The suffix has the form "_rXXXX", where XXXX stands for the row number 
+in the input table. The suffix is appended before the file name extension.
+The task recognizes as valid image name extensions the values ".??h",
+".fits" and ".fit". Any other extension is assumed to be part of the root
+file name. If only one row is extracted, no suffixing takes place.
+
+NOTE: Be careful when using a wildcard for the extension.
+If you have the files "table.tab" and "table.lis" in the current directory,
+for example, then the command "tximage tab* test/" would expand both files 
+to the subdirectory "test".
+
+Basic column information describing the column where the image came from
+is written into the image header in the "COLDATA" keyword. This information
+can be used later by task 'tiimage' to re-insert the image into a cell of 
+a 3-D table.
+
+The task does not propagate array dimensionality when extracting arrays
+into images. If dimensionality information exists in the 3-D table, that 
+information is lost, that is, the table cell from the input table is written 
+as a structureless, plain 1-D image.
+
+The input row number is written to the header of the output image in
+keyword ORIG_ROW. This allows 'tiimage' to put the data back where 
+'tximage' got them from.
+.ih
+PARAMETERS
+.ls intable [file name list/template]
+A list of one or more tables to be expanded. A column selector selecting
+a single column is mandatory. Row selectors are supported as well.
+.le
+.ls output [file name template]
+Either a directory name or a list of output image names.
+.le
+.ls (verbose = yes) [boolean]
+Display names of input and output files ?
+.le
+.ih
+EXAMPLES
+Extract 1-D images from a column named FLUX from rows 11 to 13 of a 3-D 
+table:
+
+.nf
+cl> tximage "table.tab[c:FLUX][r:row=(11:13)]" image
+.fi
+
+This will generate three images named "image_r0011", "image_r0012"
+and "image_r0013".
+.ih
+BUGS
+.ih
+REFERENCES
+This task was written by I. Busko.
+.ih
+SEE ALSO
+tiimage, selectors
+.endhelp
diff --git a/pkg/utilities/nttools/threed/doc/txtable.hlp b/pkg/utilities/nttools/threed/doc/txtable.hlp
new file mode 100644
index 00000000..462b8b95
--- /dev/null
+++ b/pkg/utilities/nttools/threed/doc/txtable.hlp
@@ -0,0 +1,89 @@
+.help txtable Jan97 tables
+.ih
+NAME
+txtable -- Extract rows from a 3-D table into separate 2-D tables.
+.ih
+USAGE
+txtable intable outtable
+.ih
+DESCRIPTION
+This task extracts one or more rows from a 3-D table and writes each row
+as a 2-D table. The input may be a filename template, including 
+wildcard characters, or the name of a file (preceded by an @ sign) containing 
+table names.  The output may be either a directory specification or a list 
+of table names. If the output is a list of tables then there must be the same 
+number of names in the input and output lists, and the names are taken in 
+pairs, one from input and one from output. The input and output tables must 
+not be the same.
+
+This task supports row/column selectors in the input table name. These
+may be used to select subsets of both rows and columns from the input table.
+If no selectors are used, all columns will be extracted, and the number
+of output tables will be the number of rows in the input table.
+Type 'help selectors' to see a description of the selector syntax. 
+
+Since one input table may generate several output tables, the task adopts
+the following naming scheme for these output tables: their names are
+built by appending a suffix to the name given in parameter "outtable".
+The suffix has the form "_rXXXX", where XXXX stands for the row number 
+in the input table. The suffix is appended before the file name extension.
+The task recognizes as valid table name extensions the values ".tab",
+".fits" and ".fit". Any other extension is assumed to be part of the root
+file name. If only one row is extracted, or in case of ASCII output, no 
+suffixing takes place.
+
+NOTE: Be careful when using a wildcard for the extension.
+If you have the files "table.tab" and "table.lis" in the current directory,
+for example, then the command "txtable tab* test/" would expand both files 
+to the subdirectory "test".
+
+There are two forms of handling scalar columns in the input table. If
+task parameter "compact" is set to 'no', the corresponding column in the
+output table will have the scalar value in its first row, and all other
+rows will be filled with INDEF. If parameter "compact" is set to 'yes',
+scalar columns will be written into the header as a set of header keywords.
+These keywords can be used later by task 'titable' to re-insert the
+scalars as cell elements of a 3-D table.
+
+The task does not propagate array dimensionality when extracting arrays
+into columns in the output table. If dimensionality information exists
+in the 3-D table, that information is lost, that is, the table cell from
+the input table is written as a structureless, plain table column.
+
+The input row number is written to the header of the output table in
+keyword ORIG_ROW. This allows 'titable' to put the data back where 
+'txtable' got them from.
+.ih
+PARAMETERS
+.ls intable [file name list/template]
+A list of one or more tables to be expanded. Row/column selectors are supported.
+.le
+.ls outtable [file name template]
+Either a directory name or a list of output table names. The standard
+value "STDOUT" generates ASCII output that can be redirected to a file.
+.le
+.ls (compact = yes) [boolean]
+Write scalars as header keywords ?
+.le
+.ls (verbose = yes) [boolean]
+Display names of input and output tables as files are processed ?
+.le
+.ih
+EXAMPLES
+Extract columns named FLUX and WAVELENGTH from rows 11 to 13 of a 3-D table:
+
+.nf
+cl> txtable "table.tab[c:FLUX,WAVELENGTH][r:row=(11:13)]" tableout
+.fi
+
+This will generate three tables named "tableout_r0011", "tableout_r0012"
+and "tableout_r0013".
+.ih
+BUGS
+.ih
+REFERENCES
+This task was written by I. Busko.
+.ih
+SEE ALSO
+titable, selectors
+.endhelp