STScI Logo

imtab tables



imtab -- Create a table from an image.


imtab input outtable colname


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.


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.


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

	tt> imtab hr465_flux.imh flux

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

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

3. Copy the 1-D section [257:257,129:384] of x0y70206t.d0h to column "x0y70206" of table "". 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] 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"



This task was written by Phil Hodge.


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.

Source Code · Search Form · STSDAS