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