Initial commit

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.