diff options
Diffstat (limited to 'sys/imio/doc/IMH.hlp')
| -rw-r--r-- | sys/imio/doc/IMH.hlp | 219 |
1 files changed, 219 insertions, 0 deletions
diff --git a/sys/imio/doc/IMH.hlp b/sys/imio/doc/IMH.hlp new file mode 100644 index 00000000..0599843b --- /dev/null +++ b/sys/imio/doc/IMH.hlp @@ -0,0 +1,219 @@ +.help imio Mar86 "Image I/O Modifications" +.ce +\fBImage I/O Modifications to Support Multiple Data Formats\fR +.ce +Doug Tody +.ce +March 16, 1986 + +.nh +Introduction + + The primary purpose of this revision of IMIO was to add support for +multiple disk data formats. This was done by defining a new interface +called IMH, which hides the details of how images are stored on disk from +the IMIO code. IMIO is concerned only with image i/o based on an internal +image descriptor. IMIO calls IMH to perform all imagefile management +operations, but accesses the pixel data directly using the FIO interface. +The IMH interface initially supports only the old IRAF and SDAS image formats, +but may be extended to support other formats in the future if necessary. +The IMH interface should be reusable in the future when IMIO is layered +upon DBIO. + +A secondary purpose of this revision was to make several minor enhancements +to IMIO to better support groups of images. The image template syntax +has been extended to provide a special selection syntax for specifying the +subset of the images in a group or set of groups to be operated upon. +Minor changes were made to the filenames of the files used to store IRAF +format images to make identification of the header and pixel files easier. +The image database interface (IDB) has been extended to permit the storage +of one dimensional arrays in the image header. IMIO was modified to use the +static file driver rather than the regular binary file driver to access +pixel data. + +.nh +Image Templates +.nh 2 +Image Template Syntax + + An image template is an expression used to specify the set or group of +images to be operated upon. The current image template syntax is upwards +compatible with the planned DBIO record select/project syntax. The full +syntax is as follows. + + images [,images ...] + +where \fIimages\fR is an expression built up from some combination of the +following constructs: + +.nf + @listfile take strings from a listfile + pattern expand pattern against database + str // str concatenate strings + {select} select elements from a set + [section] append image section +.fi + + +These elements may appear in any order, although not all orderings make +sense. The \fIpattern\fR string may contain any of the standard pattern +matching characters, but the pattern matching meta-characters {} (ignore +case) and [] (character class) must be escaped to avoid interpretation as +the subset selection and image section operators. An \fIimages\fR string +may contain at most one list construct, i.e., listfile reference, pattern, +or selection set. The \fIselect\fR expression is limited to a range list +at present. The range list syntax uses the : range syntax, i.e., +"from[:to[:by]]". Some examples are given below. None of templates shown +in these examples need be quoted if entered in the CL command mode. + + +.nf + pix one image + pix.0013 one image + @pics list of images + pix[*,-*] one image section + @pics[*,-*] list of image sections + pix.* all pix.whatever images in cwd + pix.*//.flat same, but append ".flat" to image name + pix.*//.flat[*,5] same, but append image section too + pix{1,4,9:21} pix.0001, pix.0004, and 9 through 21 + pix{1,4,9:21}[1:10,5] same, but append section to each one +.fi + + +Note that \fIselect\fR expressions are expanded without checking to see if the +named images actually exist. Image names are formed by concatenating the +image number encoded as a four digit string, padding with zeroes at the left +as in the examples. + +.nh 2 +Image Template Procedures + + The image template package (IMT) is an existing package. The calling +sequences are identical to those of the FNT (FIO filename template) package +and have not been changed in this release of the package. Extensive changes +have however been made internally, and the new package has been installed +in IMIO. The old package has been removed from the XTOOLS library. To use +the new version of the package, all one need do is relink. + + +.ks +.nf + list = imtopen (template) + nimages = imtlen (list) + imtrew (list) + nchars|EOF = imtgetim (list, fname, maxch) + imtclose (list) +.fi +.ke + + +An image template is expanded into a list of image names or image sections +with \fBimtopen\fR. The list is not globally sorted, however sublists +generated by pattern matching are sorted before appending the sublist to +the final list. The number of images or image sections in a list is given by +\fBimtlen\fR. Images are read sequentially from the list with \fBimtgetim\fR, +which returns EOF when the end of the list is reached. The list may be +rewound with \fBimtrew\fR. An image template list should be closed with +\fBimtclose\fR to return the buffers used to store the list and its +descriptor. + +.nh +The Image Header Access Interface (IMH) + + The image header access interface (IMH) is a new interface in this release +of IMIO. The purposes of the IMH interface are to hide knowledge of how images +are stored on disk from the rest of the system, and to make it possible to +support multiple image storage formats. IMIO is not aware that there are +multiple image storage formats. When called to open an existing image, +IMH determines the image format and calls the appropriate lower level access +procedure to read the image header. A standard set of IMH callable interface +procedures are required for each supported storage format. + +The IMH package is intended as an internal IMIO package and should not normally +be called by packages other than IMIO. + + +.ks +.nf + im = imh_open (image, acmode, o_im) # open/create header + imh_opix (im, acmode) # open/create pixels + imh_update (im) # update header + imh_close (im) # close image + + y/n = imh_access (image, type) # test if image exists + imh_delete (image) # delete an image + imh_rename (oldname, newname) # rename an image + imh_copy (oldname, newname) # copy an image +.fi +.ke + + +The \fIimh_open\fR procedure will open an existing image, create a new +image, or make a new copy of an existing image (preserving the header +of the old image but not the pixels). A pointer to an IMIO binary image +descriptor is returned; when opening an existing image, the primary +function of \fIimh_open\fR is to map the disk image header, stored in +whatever format, into the IMIO fixed format binary descriptor. + +The \fIimh_opix\fR procedure must be called after the header has been opened +before any pixel i/o can be done to the image. In the case of a new image +the size attributes of the new image are not fixed until \fIimh_opix\fR is +called (giving the high level code time to set the size parameters in the +image descriptor). It is not necessary to call \fIimh_opix\fR if only the +header of an existing image is to be accessed. + +The \fIimh_access\fR procedure is provided to test if the named image +exists (no test is made to determine if the image is also accessible). +An integer code identifying the storage format of the image, e.g., old +IRAF or SDAS, is returned in the \fItype\fR argument. Currently, the type +of an image is indicated by the filename extension of the header file. + +The \fIimh_rename\fR and \fIimh_copy\fR procedures are in principle not +required since the operations can be performed at a high level with the +procedures already provided, but the IMH operators can carry out the +operations more efficiently and without the possibility of information being +lost, since they have knowledge of the physical storage format. + +.nh +Physical Data Formats + + The only two physical (disk) data formats currently supported are the +old IRAF format and the STScI SDAS format. The IMH interface makes it +relatively straightforward for other sites to interface their local format +if necessary, or to support multiple versions of the same format. + +IMH will automatically read images stored in any of the supported formats. +When making a NEW_COPY image, IMH will generate a new image in the same +format as the existing input image. When making a NEW_IMAGE type image, +the value of the environment variable \fBimtype\fR determines the type of +image to be created. The recognized values of \fBimtype\fR are shown below. + +.ks +.nf + not defined old iraf format + imtype = "oiraf" old iraf format + imtype = "sdas" SDAS/SOGS format +.fi +.ke + +The format in which an image is stored is indicated by the filename extension +of the header file. The filename extension is not specified in image names +or templates above the IMH interface, but is visible to the user in a +directory listing. + +.ks +.nf + .imh old iraf format header + .hhh SDAS/SOGS format header +.fi +.ke + +The current IMH interface is implemented in such a way that the semantics +of the two image storage formats are essentially equivalent, i.e., applications +programs should work consistently regardless of the storage format used. +In order to achieve this, the SDAS group format is fully supported only +when reading existing group format images. On output, images stored in +SDAS format are stored in separate files (gcount=1). The IRAF image template +is more flexible than the SDAS group format, simplifies programming, and +provides much the same basic capability. |