1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
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
|
