imtab: Copy an image to a table column.

Package: nttools

Usage

imtab input outtable colname

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.

Parameters

input = "" [file name template]: The names of the images to be written to the tables.

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.

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.

(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.

(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.

(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.

(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.

Examples

1. Copy image "hr465_flux.imh" to table "hr465.tab", column "flux":

tt> imtab hr465_flux.imh hr465.tab flux

2. Copy the 2-D image "ir27.hhh" to column "ir27" of table "map.tab", saving the pixel numbers in columns "pix1" and "pix2":

tt> imtab ir27.hhh map.tab ir27 pname="pix"

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.

tt> imtab x0y70206t.d0h[257:257,129:384] focus.tab x0y70206 \
>>> pname="p" wcs="world" formats="%12.1H %12.1h"

4. Use the same image as in the previous example, but print the values on the standard output.

tt> imtab x0y70206t.d0h[257:257,129:384] STDOUT x0y70206 \
>>> pname="p" wcs="world" formats="%12.1H %12.1h"

Bugs

References

This task was written by Phil Hodge.