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
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
|
.help imextensions Jul97 proto
.ih
NAME
imextensions -- make a list of image extensions
.ih
USAGE
.nf
imextensions input
.fi
.ih
PARAMETERS
.ls input
List of input files containing image extensions to be listed. This list
may not contain any image kernel but it can contain an image section. The
image filename extension, such as ".fits", is optional in the same way as
with other IRAF image tasks.
.le
.ls output = "file" (none|list|file)
Output type for the list of image extensions. The choices are:
.nf
none - no output
list - a list as a single line
file - a list of one image extension per line
.fi
The "none" output is used to just set the number of image extensions in the
\fInimages\fR parameter. The "list" output is used for a short list that
can be scanned into a CL variable. The "file" output is used for a long
list and to be redirected to a file for use as an "@file". If "list"
output is selected and the list length exceeds 255 characters (the
size of a CL string) the task will abort with an error.
.le
.ls index = "1-"
Extension index range list. The range list syntax is specified under the
help topic \fBranges\fR. Note that the range list may be specified that
includes 0 to select the primary image header in FITS files.
.le
.ls extname = ""
Extension name pattern. If a null string is specified then there is
no check on the extension name. If a pattern is specified then only
image extensions with an extension name matching the pattern will be
selected. The pattern syntax is described under the help topic \fImatch\fR.
.le
.ls extver = ""
Extension version range list. If a null list is specified then there is
no check on the extension version. If a list is given then only image
extensions with extension versions in the list will be selected.
The range list syntax is described under the help topic \fBranges\fR.
.le
.ls lindex = yes
List the image extensions with the extension index? If the value is
"no" then the extension index will not be listed if the extension
name and/or the extension version is listed. If there is no
extension name or extension version then the extension index is
always listed regardless of the value of this parameter.
.le
.ls lname = no
List the image extensions with the extension name if there is one?
.le
.ls lver = no
List the image extensions with the extension version if there is one?
.le
.ls ikparams = ""
Include the specified image kernel parameters in the image extension
names. The image kernel parameters are specific to the various
IRAF image formats.
.le
.ls nimages
This is an output parameter which is set to the number of image extensions
selected in the last execution of the task. Note that if the task
is run as a background job this parameter will not be set in the
disk parameter file though it can be made available in a background
script using this task by caching the parameter set; i.e.
include the command "cache imextensions" at the beginning of the script.
.le
.ih
DESCRIPTION
\fBImextensions\fR selects and lists image extensions in files. Image
extensions currently occur in multi-extension FITS files and multi-group
Geiss (STF format) files. The image extension names are given in proper
syntax for IRAF image names for use in tasks expecting image names.
The output format type may be a one line list, a list of one image
extension name per line, or no output. These options allow capturing
the expanded list in a CL string variable, in a file for use as
an "@file", or to simply count the number of image extensions matching
the selection criteria. Note that if the "list" output type is selected
and the list of image extensions exceeds 255 characters (the limit
for a CL string) then the task aborts with an error.
Image extensions may be selected by index value (the position in the file),
by extension name (keyword EXTNAME used in FITS image extensions), and by
extension version number (keyword EXTVER). The numeric selection uses
range lists and the extension name selection uses pattern matching. The
primary image in a multi-extension FITS file may also be selected by
including an index value of 0 in the index range list.
The output image extension names may be given with the index value and/or
the image kernel specification. The image kernel specification, which is
image type dependent, may include the extension name, extension version,
and other kernel parameters. Note that if the image does not have an
extension name or version then the index value is always given whether or
not the \fIlindex\fR parameter is set to insure that a proper image name is
generated.
.ih
EXAMPLES
1. Get a list of image extensions in a CL string and use it to select
header keywords. This illustrates the use of the "list" output and
a CL variable.
.nf
cl> imext obj001 output=list | scan (s1)
cl> = s1
obj001[1],obj001[2],obj001[3]
cl> if (imext.nimages > 0)
>>> hselect (s1, "$I,title", yes)
obj001[1] Alpha Leo
obj001[2] Beta Leo
obj001[3] Gamma Leo
.fi
2. Do the same thing as in the first example using an "@file".
.nf
cl> imext obj001 output=file > list.dat
cl> type list.dat
obj001[1]
obj001[2]
obj001[3]
cl> if (imext.nimages > 0)
>>> hselect @list.dat $I,title yes
obj001[1] Alpha Leo
obj001[2] Beta Leo
obj001[3] Gamma Leo
.fi
3. Create a list selecting only the first and third extension and using the
image extension name, version, and an image kernel section.
.nf
cl> imext obj*[1:100,1:100] index=1,3 lindex- lname+ lver+ ikparams=expand
obj001.fits[aleo,1,expand][1:100,1:100]
obj003.fits[gleo,1,expand][1:100,1:100]
obj002.fits[im1,1,expand][1:100,1:100]
obj002.fits[im3,1,expand][1:100,1:100]
cl> = imext.nimages
4
.fi
4. List only the primary images in a set of multi-extension FITS files.
A primary image need not contain image data; i.e. this will select
global headers with NDIM=0 as well as headers with image data.
.nf
cl> imext *.fits index=0
abc.fits[0]
def.fits[0]
ghi.fits[0]
.fi
5. Use this task in a script to test on the existence of extension name
"joy". This example shows the use of the pattern matching and of the
\fBcache\fR command to insure the script works as a background task.
.nf
procedure example (image)
file image {prompt="Image"}
begin
file im
cache imextensions
im = image
imextensions (im, output="none", extname="joy")
if (imextensions.nimages == 0)
call printf ("No joy found with %s\n", im)
end
.fi
Note that proper script programming would make all the hidden parameters
explicit.
6. Example of the extension name pattern matching.
.nf
cl> imext obj.fits extname=joy lindex- lname+
obj.fits[joy]
obj.fits[nojoy]
obj.fits[joyfull]
cl> imext obj.fits extname="^joy$" lindex- lname+
obj.fits[joy]
cl> imext obj.fits extname="{joy}$" lindex- lname+
obj.fits[joy]
obj.fits[Joy]
obj.fits[nojoy]
.fi
The first example matches "joy" anywhere in the extension name, the
second requires an exact match with the begin and end string characters,
and the last example ignores the case and requires the name end with
joy.
7. An example with a Geiss file.
.nf
cl> imext y00vk102r.d0h index="x5"
y00vk102r.d0h[1]
y00vk102r.d0h[6]
y00vk102r.d0h[11]
y00vk102r.d0h[16]
y00vk102r.d0h[21]
y00vk102r.d0h[26]
y00vk102r.d0h[31]
y00vk102r.d0h[36]
.fi
.ih
REVISIONS
.ls IMEXTENSIONS V2.11.?
Image sections are now allowed in the input names.
.le
.ls IMEXTENSIONS V2.11
This task is new in this release.
.le
.ih
SEE ALSO
.nf
files, sections, ranges, match
.fi
.endhelp
|
