chkimg (Aug2004) |
rjtools
|
chkimg (Aug2004) |
chkimg
chkimg - Check (non-)existence of images/files, and parse their name
chkimg image check [imtype] [verbose]
- image = ""
- Image or file to check the (non-)existence of and parse the name of.
- check = "access" (access|noacces)
- Type of check to perform: whether the file exists, or whether the file
does not exist.
- imtype = ""
- Search only images of this type when specified. The special value "file"
allows searching for any file of the given name and does not split 'image'
into a image root and an extension part. When blank upon input, the task
will search only for images of the current default image type and return
it in this parameter.
- (ok) [boolean]
- Parameter returning the result of the check performed. Its meaning depends
on 'check'.
- (imroot) [string]
- Parameter returning the image root portion of 'image', exclusive of any
path or image extension.
- (impath) [string]
- Parameter returning the path to 'image', where the path is defined as any
portion of 'image' up to any including the last slash ("/") found within
string 'image'. If 'image' resides in the current working directory, the
path returned will be an empty string (""). Symbolic paths (e.g., "dev$")
are expanded first to absolute paths ("/iraf/iraf/dev/").
- (imrlen) [int]
- Parameter returning the length (number of characters) of the image root
name.
- (implen) [int]
- Parameter returning the length of the path to the image or file.
- (imglen) [int]
- Parameter returning the length of 'image' exclusive of the image
extension, if present.
- (imrpstr) [string]
- Image region and/or plane string, if any. If 'image' contains a "[" or "]"
it is assumed to indicate a section or a section and image plane specifier.
The format is tested and if valid, returned in this parameter. A valid
region/plane string is defined to have the generic format:
[extn][x1:x2,y1:y2], where "[extn]" is optional. Also, "x1:x2" and/or
"y1:y2" may be replaced by a "*".
- (iostat) [int]
- Parameter returning the integer I/O status, where 1 means that 'image'
exists and "0" that it does not.
- verbose = yes
- Print a meaningful error message on exit? If 'verbose=no' all error
messages are suppressed. This allows flexible error handling in the calling
subroutine, or even to use this task to just parse a file name corresponding
to an image or file that may or may not yet exist.
Task to check the I/O status of an image or file, and parse and return
the image specified into a path, image root and image extension. The
'check' switch controls whether the task tests for existence or
non-existence of 'image'. If 'imtype' is non-empty upon invokation of
"chkimg", only images of type 'imtype' will be searched, otherwise
images of the current default image type are searched and that current
default image type is returned. The special value "file" for 'imtype'
disables splitting the image name into a root and extension, allowing to
test the existence of a non-image file and return the path and length of
its name. The 'iostat' parameter returns the I/O status of the image
regardless of 'check', where "0" means that the image does not exist and
"1" that is does. The verbose switch allows for an error message to be
returned to the standard output, the value of which depends on 'check'.
When either 'imtype' is given explicitly, or when the image has the
default image type, an image extension and/or section specifier may be
appended directly to the image root name in 'image', without first specifying
the image type: "bla[3:128,*]" instead of "bla.fits[3:128,*]".
The latter, of course, would also be valid. If an image extension
and/or section specifier are part of 'image', they are checked for validity
(see 'rpparse') and a diagnostic error message is returned when the format
is incorrect.
This task and 'rpparse' were motivated in part by the fact that native IRAF
file and image template facilities ('files' and 'sections') do not check
whether file/image exists and whether a section given as part of an image
template is indeed a valid image section.
1. Check whether image "dev$pix.fits" exists (the default image type in
this example is "fits"):
rj> chkimg dev$pix access imtype=""
ERROR: Image "/iraf/iraf/dev/pix.fits" not found!
Note how the symbolic path is translated into an absolute one.
2. Check that image "dev$pix.imh" does not already exists (the image
extension is explicitly given here, so we need not change the default
image type):
rj> chkimg dev$pix noaccess imtype="imh" verbose+
ERROR: Image "/iraf/iraf/dev/pix.imh" already exists!
rj> lpar chkimg
image = "dev$pix" image or file name
check = "noaccess" check for (access|noaccess)
(imtype = ".imh") image file format
(ok = no) result of I/O check?
(imroot = "pix") image root name
(impath = "/iraf/iraf/dev/") image path name
(imrlen = 3) length of image root name
(implen = 15) length of image path name
(imglen = 18) length of image root+path name
(imrpstr = "") image region/plane
(iostat = 1) integer I/O status
(verbose = yes) verbose error message?
(mode = "ql")
We see that 'chkimg.ok = no' for the check that "dev$pix" does not already
exist and an integer I/O status of 1, indicating that, indeed, "dev$pix"
does exist. A calling routine now has access to the system path to the
image and the image root name ('chkimg.impath' and '-.imroot') and the
length of both character strings ('chkimg.implen' and '-.imrlen').
3. We can use 'chkimg' to test the format of a region/plane string appended
to its name, or if we know it to be correct already, we can split it off of
the image name for further use:
rj> chkimg dev$pix[3,128:2,127] access imtype="imh" verbose+
ERROR: unsupported 3-D section or switched comma and colon:
"[3,128:2,127]"
or one could write in a subroutine:
chkimg ("dev$pix[3:128,2:127]", "access", imtype="imh", verbose+)
if ( chkimg.ok ) {
imstat ("dev$pix[3:128,2:127]")
} else { return }
in the latter case the task parameters upon exit are:
image = "dev$pix[3:128,2:127]" image or file name
check = "access" check for
(imtype = ".imh") image file format
(ok = yes) result of I/O check?
(imroot = "pix") image root name
(impath = "/iraf/iraf/dev/") image path name
(imrlen = 3) length of image root name
(implen = 15) length of image path name
(imglen = 18) length of image root+path name
(imrpstr = "[3:128,2:127]") image region/plane
(iostat = 1) integer I/O status
(verbose = yes) verbose error message?
(mode = "ql")
- CHKIMG v2.10, Feb 04 1998 [R.A. Jansen]
- Original version of this task. The integer rather than boolean I/O status
parameter is for backward compatibility with some routines based on
'imfort'; IRAF 2.10.4
- CHKIMG v2.11, Jun 14 2000 [RAJ]
- Added support for multi-extension images and image sections; IRAF 2.11.3
- CHKIMG v2.12, Jul 12 2003 [RAJ]
- Added distinction between path and true root of an image name and added
corresponding parameters 'impath', 'implen', and 'imrlen'. Converted a
'stridx'-based loop into a single 'translit' statement with pipes; IRAF
2.12.1
- CHKIMG v2.12, Aug 12 2003 [RAJ]
- Captured the special case of 'image = "" && imtype = "file"' to properly
return the system path to the current working directory (native IRAF task
'access("")' returns "no"); IRAF 2.12.1