Initial commit

1 files changed, 169 insertions, 0 deletions

diff --git a/pkg/utilities/nttools/doc/imtab.hlp b/pkg/utilities/nttools/doc/imtab.hlp
new file mode 100644
index 00000000..a2438f8a
--- /dev/null
+++ b/pkg/utilities/nttools/doc/imtab.hlp
@@ -0,0 +1,169 @@
+.help imtab Mar2000 tables
+.nj
+.ih
+NAME
+imtab -- Create a table from an image.
+.ih
+USAGE
+imtab input outtable colname
+.ih
+DESCRIPTION
+This task copies data from an image to a table.
+Pixel values are read from the image line by line
+and written to a column in increasing row number.
+The image may be of any dimension,
+but a single column is written.
+If the table already exists then columns will be added to it;
+names of new columns must not conflict with existing names.
+If the table does not exist it will be created.
+
+The number of names in the 'input' list must be the same as
+the number of names in the 'outtable' list,
+unless 'outtable' is "STDOUT".
+
+Information about the image dimension and axis lengths will not be kept
+in keywords, but there is an option to write the image pixel numbers
+to columns of the table.
+The pixel coordinates may be just the pixel numbers,
+or they may be world coordinates at the pixel locations.
+
+A history record will be added to the table giving
+the name of the data column and the name of the image.
+If pixel coordinates are written to the table,
+another history record is written that also gives
+the column name for the image data
+and gives the column names for the pixel coordinates.
+.ih
+PARAMETERS
+.ls input = "" [file name template]
+The names of the images to be written to the tables.
+.le
+.ls outtable = "" [file name template]
+The names of the output tables.
+If outtable = "STDOUT" or if the output has been redirected,
+the values will be written to the standard output.
+
+If the output table is of type text (e.g. STDOUT),
+the data values will be in the first column.
+If the pixel coordinates are also printed,
+they will be in the following columns.
+.le
+.ls colname = "" [string]
+A column of this name will be created in the output table,
+and the values of the image will be written to this column.
+The same column name will be used for all output tables.
+.le
+.ls (pname = "") [string]
+If 'pname' is not null,
+the pixel coordinates will also be written to columns of the table.
+The names of these columns will be the value of 'pname' with the
+numbers 1, 2, 3, etc appended,
+corresponding to the sample number, line number, band number, etc.
+This may be especially useful for a multi-dimensional input image,
+since all the data values are written to one column.
+The same column names will be used for all output tables.
+See also 'wcs' and 'formats'.
+
+If 'pname' is null (or blank) the pixel numbers will not be written.
+.le
+.ls (wcs = "logical") [string, allowed values:  logical | physical | world]
+This parameter is only gotten if 'pname' is not null.
+In this case, the user has the option of which coordinate system
+should be used when writing pixel coordinates to the table.
+The "logical" coordinates are simply the pixel numbers
+of the image or image section.
+The "physical" coordinates are also pixel numbers,
+but they can differ from logical coordinates
+if an image section has been taken.
+Physical coordinates have the same origin and sampling as the original image.
+The "world" coordinates are coordinates such as wavelength, time,
+or right ascension and declination.
+The translation from logical to world coordinates is given by
+header keywords CRVAL1, CRPIX1, CD1_1, CTYPE1, etc.
+
+The number of pixel coordinates written by 'imtab' differs from
+the number written by 'listpixels' when wcs = "physical" or "world"
+and an image section was used that reduces the dimension of the image.
+'imtab' gives one pixel coordinate column for each dimension
+of the original image, while 'listpixels' gives one pixel coordinate
+for each dimension of the image section.
+
+Type "help mwcs$MWCS.hlp fi+" for extensive information on coordinate systems.
+.le
+.ls (formats) [string]
+The print formats to use for the pixel coordinates, one format
+per axis, with the individual formats separated by whitespace.
+This parameter is only gotten if 'pname' is not null.
+If the formats are not given, a default format is assigned.
+See the help for 'listpixels' for extensive information on formats.
+These formats are saved in the descriptors for the table columns,
+so these formats will be used if the table is printed.
+If the output table is text rather than binary,
+these formats will be used to write the coordinates to the text table.
+.le
+.ls (tbltype = "default") [string, allowed values: default | row |
+column | text ]
+
+If the output table does not already exist,
+you can specify whether the table should be created in row or column
+ordered format.
+As an alternative to a binary table,
+tbltype = "text" means the output will be a plain text file.
+.le
+.ih
+EXAMPLES
+1.  Copy image "hr465_flux.imh" to table "hr465.tab", column "flux":
+
+.nf
+	tt> imtab hr465_flux.imh hr465.tab flux
+.fi
+
+2.  Copy the 2-D image "ir27.hhh" to column "ir27" of table "map.tab",
+saving the pixel numbers in columns "pix1" and "pix2":
+
+.nf
+	tt> imtab ir27.hhh map.tab ir27 pname="pix"
+.fi
+
+3.  Copy the 1-D section [257:257,129:384] of
+x0y70206t.d0h to column "x0y70206" of table "focus.tab".
+Also write the right ascension and declination
+("world" coordinates) to columns "p1" and "p2" respectively
+using HH:MM:SS.d and DD:MM:SS.d formats.
+We use "%12.1H" for right ascension and "%12.1h" for declination.
+The capital "H" in the format means that the values will be divided by 15
+to convert from degrees to hours before formatting in sexagesimal.
+Note that we get two columns of pixel coordinates even though
+the image section is only 1-D.
+Physical or world coordinates will be 2-D in this case
+because the original image "x0y70206t.d0h" is 2-D.
+
+.nf
+	tt> imtab x0y70206t.d0h[257:257,129:384] focus.tab x0y70206 \
+	>>> pname="p" wcs="world" formats="%12.1H %12.1h"
+.fi
+
+4.  Use the same image as in the previous example,
+but print the values on the standard output.
+
+.nf
+	tt> imtab x0y70206t.d0h[257:257,129:384] STDOUT x0y70206 \
+	>>> pname="p" wcs="world" formats="%12.1H %12.1h"
+.fi
+.ih
+BUGS
+.ih
+REFERENCES
+This task was written by Phil Hodge.
+.ih
+SEE ALSO
+The 'tabim' task copies a column of a table to an image.
+The 'listpixels' task in the 'images' package writes data values and
+pixel coordinates to the standard output.
+The parameters 'wcs' and 'formats' are the same in 'imtab' and 'listpixels'.
+For detailed information on the distinction between logical, physical and
+world coordinates, type "help mwcs$MWCS.hlp fi+".
+
+Type "help tables option=sys" for a higher-level description of
+the tables package.
+.endhelp