imextensions: Make a list of image extensions

Package: proto

Usage

imextensions input

Parameters

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.

output = "file" (none|list|file)

Output type for the list of image extensions. The choices are:

none - no output
list - a list as a single line
file - a list of one image extension per line

The "none" output is used to just set the number of image extensions in the nimages 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.

index = "1-": Extension index range list. The range list syntax is specified under the help topic ranges. Note that the range list may be specified that includes 0 to select the primary image header in FITS files.

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

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

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.

lname = no: List the image extensions with the extension name if there is one?

lver = no: List the image extensions with the extension version if there is one?

ikparams = "": Include the specified image kernel parameters in the image extension names. The image kernel parameters are specific to the various IRAF image formats.

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.

Description

Imextensions 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 lindex parameter is set to insure that a proper image name is generated.

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.

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

2. Do the same thing as in the first example using an "@file".

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

3. Create a list selecting only the first and third extension and using the image extension name, version, and an image kernel section.

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

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.

cl> imext *.fits index=0
abc.fits[0]
def.fits[0]
ghi.fits[0]

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 cache command to insure the script works as a background task.

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

Note that proper script programming would make all the hidden parameters explicit.

6. Example of the extension name pattern matching.

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]

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.

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]

Revisions

IMEXTENSIONS V2.11.?: Image sections are now allowed in the input names.

IMEXTENSIONS V2.11: This task is new in this release.