path: root/sys/imio/doc/imio.hlp

.help imio May83 "Image I/O Routines"
.sh
The Image Header

    The major difference between the prototype IMIO interface, and the final
interface, concerns the way in which the image header is implemented and
accessed.  In the prototype version, we will simply read the entire header
into core and access it as an ordinary (dynamically allocated) structure.


.nf
	ptr =	immap (fname, mode, hdrsize/hdrptr)
	      imunmap (hdrptr)
.fi


The final resolution of how image headers are implemented depends on how
we decide to implement virtual structures in the spp language.  The immap
calls, and the techniques used to access the fields of the image header,
can be expected to change.

.sh
Pixel I/O

    The calling sequences for the i/o routines, described below, hopefully will
not have to be changed.  We will eventually add GETPIX and PUTPIX statements
to the subset preprocessor language, to automatically generate the appropriate
low level calls.

A generic, polymorphic GETPIX or PUTPIX statement is translated into a
reference to a low level Fortran function.  The transformation is governed
by the following subprogram name generating function:


.rj (108 total)
GETPIX, PUTPIX -->  im[gp][pls][123][silrdx]


.ks
.nf
For example (get, type real):

	ptr =	imgp1r (hdrptr, x, npix)		# get pixels
	ptr =	imgp2r (hdrptr, x, y, npix)
	ptr =	imgp3r (hdrptr, x, y, z, npix)

	ptr =	imgl1r (hdrptr)				# get line
	ptr =	imgl2r (hdrptr, y)
	ptr =	imgl3r (hdrptr, y, z)

	ptr =	imgs1r (hdrptr, x1, x2)			# get section
	ptr =	imgs2r (hdrptr, x1, x2, y1, y2)
	ptr =	imgs3r (hdrptr, x1, x2, y1, y2, z1, z2)
.fi
.ke


The IM?P?? procedures access a list of pixels, the coordinates of which
are given by the X, Y, Z, etc. arrays given as arguments.  Note that random
access of individual pixels is provided as a special case (npix=1).

The IM?L?? routines access the lines of an image, and the IM?S?? routines
operate on general, but connected, subsections of images.


.sh
Restrictions Imposed by the Initial Prototype:

    IMMAP, IMMAPNC, IMUNMAP will be implemented for image headers that are
simple binary structures (not self describing), subject to the restriction
that a file may contain only a single header.  An arbitrary selection of user
defined fields will follow the standard header.  The entire header will
be read into core and accessed as a simple incore structure.

The pixels, and other variable size image substructures, will be stored
in separate files, as in the general plan.  All of the standard data types
will be implemented in the disk space.  The initial implementation will
support only type REAL pixels in program space.

The following i/o routines will be implemented in the first release of
the prototype:

.rj (12 total)
	im[gp][sc][123][r]

In words, we will be able to read and write lines and sections, with the
applications program manipulating type REAL pixels internally.  The full
range of data types will be permitted in the image file as stored on disk.
Up to three dimensional images are permitted.

.sh
IMSET Options

    The prototype need not provide multiple buffering and boundary extension
initially.

.sh
Implementation

    Little effort should be made to make the prototype optimal.  All
buffering will be locally allocated, and data will be copied to and from
the FIO buffers (the FIO buffers will not be directly accessed).  Special
cases will not be optimized.  The most general entry points are IMGGSR
and IMPGSR (get/put general section).  Initially, all of the other entry
points can be defined in terms of these.


.ks
.nf
Structure of the input procedures (type REAL): 

	imgl1r
	imgl2r
	imgl3r
	imgs1r
	imgs2r
	imgs3r
		imggsr
			imggsc
				imgibf
					imopsf
					calloc
					imcssz
					realloc
					malloc
					mfree
				imsslv
				imrdpx
					imsoob
					imnote
					seek
					read
				imflip
			imupkr

  (datatype dependent) | (datatype independent)
.fi
.ke



The output procedures are structured somewhat differently, because the
transfer of a section occurs sometime after a "put section" returns,
rather than immediately as in the input procedures.  Since the output
is buffered for a delayed write, we must have an IMFLUSH entry point, and
IMUNMAP must flush the output buffer before unmapping an image.


.ks
.nf
Structure of the output procedures (type REAL): 

	impl1r
	impl2r
	impl3r
	imps1r		imunmap
	imps2r		   |
	imps3r		   |
		impgsr     |
			imflush
				imflsr
					imflsh
						imflip
						imwrpx
							imsoob
							imnote
							imwrite
								fstatus
								seek
								write
					impakr

			imgobf
				imopsf
				calloc
				imcssz
				realloc
				malloc
				mfree

          (datatype dependent) | (datatype independent)
.fi
.ke


.sh
Semicode for the Basic I/O Routines

    The IMGGS? and IMPGS? procedures get and put general N-dimensional
image sections of a specific datatype.  There is no intrinsic limit on
the maximum number of dimensions, and the full range (8) of disk datatypes
are easily supported.  The subscript for a particular dimension may run
either forward or backward.  The semicode is written generically, allowing
code to be machine generated for all program space datatypes (6).

We do not address the problems of boundary extension and multiple buffering
here, but these features can be easily added in the future.  This version
of IMIO assumes that pixels are stored on disk in line storage mode, with
no interlacing of bands.


IMGGS? gets a general section, and converts it to the datatype indicated
by the type suffix.


.ks
.nf
pointer procedure imggs$t (imdes, vs, ve)

imdes	pointer to image descriptor structure
vs,ve	coordinates of starting and ending points

begin
	bp = imggsc (imdes, vs, ve, TY_PIXEL, totpix)
	if (imdes.pixtype != TY_PIXEL)
	    call imupk$t (*bp, *bp, totpix, imdes.pixtype)
	return (coerce (bp, TY_CHAR, TY_PIXEL))
end
.fi
.ke



IMGGSC gets a general section from an imagefile into a buffer.  Upon
exit, the buffer contains the requested section, with the pixels still
in the same datatype they were in the imagefile.  The buffer is made
large enough to accommodate the pixels in either datatype.


.ks
.nf
pointer procedure imggsc (imdes, vs, ve, dtype, totpix)

imdes	pointer to image descriptor structure
vs,ve	coordinates of starting and ending points
dtype	datatype of pixels required by calling program
bp	pointer to CHAR buffer to hold pixels

begin
	# Get an (input) buffer to put the pixels into.   Prepare the
	# section descriptor vectors V, VINC.

	bp = imgibf (imdes, vs, ve, dtype)
	call imsslv (imdes, vs, ve, v, vinc, npix)

	# Extract the pixels.  IMRPIX reads a contiguous array of
	# pixels into the buffer at the specified offset, incrementing
	# the offset when done.  The pixels are type converted if
	# necessary.

	offset = 0

	repeat {
	    call imrdpx (imdes, *(bp+offset), v, npix)
	    if (vinc[1] < 0)
		call imflip (*(bp+offset), npix, sizeof(imdes.pixtype))
	    offset = offset + npix

	    for (d=2;  d <= imdes.ndim;  d=d+1) {
		v[d] += vinc[d]
		if ((v[d] - ve[d] == vinc[d]) && d < imdes.ndim)
		    v[d] = vs[d]
		else {
		    d = 0
		    break
		}
	    }
	} until (d >= imdes.ndim)

	totpix = offset
	return (bp)
end
.fi
.ke





Prepare the section descriptor vectors V and VINC.  V is a vector specifying
the coordinates at which the next i/o transfer will take place.  VINC is
a vector specifying the loop step size.


.ks
.nf
procedure imsslv (imdes, vs, ve, v, vinc, npix)

begin
	# Determine the direction in which each dimension is to be
	# traversed.

	do i = 1, imdes.ndim
	    if (vs[i] <= ve[i])
		vinc[i] = 1
	    else
		vinc[i] = -1

	# Initialize the extraction vector (passed to IMRDS? to read a
	# contiguous array of pixels).  Compute length of a line.

	do i = 1, imdes.ndim
	    v[i] = vs[i]

	if (vs[1] > ve[1]) {
	    v[1] = ve[1]
	    npix = vs[1] - ve[1] + 1
	} else
	    npix = ve[1] - vs[1] + 1
end
.fi
.ke





The put-section procedure must write the contents of the output buffer
to the image, using the section parameters saved during the previous call.
The new section parameters are then saved, and the buffer pointer is
returned to the calling program.  The calling program subsequently fills
the buffer, and the sequence repeats.


.ks
.nf
pointer procedure impgs$t (imdes, vs, ve)

imdes	pointer to image descriptor structure
vs,ve	coordinates of starting and ending points

begin
	# Flush the output buffer, if appropriate.  IMFLUSH calls
	# one of the IMFLS? routines, which write out the section.

	call imflush (imhdr)

	# Get an (output) buffer to put the pixels into.  Save the
	# section parameters in the image descriptor.  Save the epa
	# of the typed flush procedure in the image descriptor.

	bp = imgobf (imdes, vs, ve, TY_PIXEL)
	imdes.flush_epa = loc (imfls$t)

	return (bp)
end
.fi
.ke



Flush the output buffer, if a put procedure has been called, and the
buffer has not yet been flushed.  The output buffer is flushed automatically
whenever a put procedure is called, when an image is unmapped, or when
the applications program calls IMFLUSH.


.ks
.nf
procedure imfls$t (imdes)

begin
	# Ignore the flush request if the output buffer has already been
	# flushed.

	if (imdes.flush == YES) {
	    bdes = imdes.obdes
	    bp = bdes.bufptr

	    # Convert datatype of pixels, if necessary, and flush buffer.
	    if (imdes.pixtype != TY_PIXEL)
		call impak$t (*bp, *bp, bdes.npix, imdes.pixtype)
	    call imflsh (imdes)

	    imdes.flush = NO
	}
end
.fi
.ke


.ks
.nf
procedure imflsh (imdes)

begin
	# Determine the direction in which each dimension is to be
	# traversed.

	bdes = imdes.obdes
	call imsslv (imdes, bdes.vs, bdes.ve, v, vinc, npix)

	# Write out the pixels.  IMWRPX writes a contiguous array of
	# pixels at the specified offset.

	offset = 0

	repeat {
	    if (vinc[1] < 0)
		call imflip (*(bp+offset), npix, sizeof(imdes.pixtype))
	    call imwrpx (imdes, *(bp+offset), v, npix)
	    offset = offset + npix

	    for (d=2;  d <= imdes.ndim;  d=d+1) {
		v[d] += vinc[d]
		if ((v[d] - ve[d] == vinc[d]) && d < imdes.ndim)
		    v[d] = vs[d]
		else {
		    d = 0
		    break
		}
	    }
	} until (d >= imdes.ndim)
end
.fi
.ke




Read a contiguous array of NPIX pixels, starting at the point defined by
the vector V, into the callers buffer.


.ks
.nf
procedure imrdpx (imdes, buf, v, npix)

begin
	# Check that the access does not reference out of bounds.

	if (imsoob (imdes, v, npix))
	    call imerr (imname, subscript_out_of_range)

	# Seek to the point V in the pixel storage file.  Compute size
	# of transfer.

	call seek (imdes.pfd, imnote (imdes, v))
	nchars = npix * sizeof (imdes.pixtype)

	# Read in the data.
	if (read (imdes.pfd, buf, nchars, junk) != nchars)
	    call imerr (imname, missing_pixels)
end
.fi
.ke



Write a contiguous array of NPIX pixels, starting at the point defined by
the vector V, into the pixel storage file.


.ks
.nf
procedure imwrpx (imdes, buf, v, npix)

begin
	# Check that the access does not reference out of bounds.

	if (imsoob (imdes, v, npix))
	    call imerr (imname, subscript_out_of_range)

	# Seek to the point V in the pixel storage file.  Note that
	# when writing to a new image, the next transfer may occur
	# at a point beyond the current end of file.  If so, write
	# out zeros until the desired offset (which is in bounds)
	# is reached.

	file_offset = imnote (imdes, v)
	if (file_offset > imdes.file_size)
	    [write zeros until the desired offset is reached]
	else
	    call seek (imdes.pfd, file_offset)

	# Compute size of transfer.  If transferring an entire line,
	# increase size of transfer to the physical line length,
	# to avoid having to enblock the data.  NOTE: buffer must
	# be large enough to guarantee no memory violation.

	if (v[1] == 1 && npix == imdes.len[1])
	    nchars = imdes.physlen[1] * sizeof (imdes.pixtype)
	else
	    nchars = npix * sizeof (imdes.pixtype)

	call write (imdes.pfd, buf, nchars)
	imdes.file_size = max (imdes.file_size, file_offset+nchars)
end
.fi
.ke




IMNOTE computes the physical offset of a particular pixel in the
pixel storage file.  If the disk datatype is UBYTE, this is the offset
of the char containing the subscripted byte.


.ks
.nf
long procedure imnote (imdes, v)

begin
	pixel_offset = v[1]
	for (i=2;  i <= imdes.ndim;  i=i+1)
	    pixel_offset += (v[i]-1) * imdes.physlen[i]

	char_offset0 = (pixel_offset-1) * sizeof (imdes.pixtype)
	return (imdes.pixoff + char_offset0)
end
.fi
.ke



Convert a vector of any datatype to type PIXEL ($t).  The input and
output vectors may be the same, without loss of data.  The input and
output datatypes may be the same, in which case no conversion is
performed.


.ks
.nf
procedure imupk$t (a, b, npix, dtype)

begin
	switch (dtype) {
	case TY_USHORT:
	    call achtu$t (a, b, npix)
	case TY_SHORT:
	    call achts$t (a, b, npix)
	case TY_INT:
	    call achti$t (a, b, npix)
	case TY_LONG:
	    call achtl$t (a, b, npix)
	case TY_REAL:
	    call achtr$t (a, b, npix)
	case TY_DOUBLE:
	    call achtd$t (a, b, npix)
	case TY_COMPLEX:
	    call achtx$t (a, b, npix)
	default:
	    call syserr (unknown_datatype_in_imagefile)
	}
end
.fi
.ke



Convert a vector of type PIXEL ($t) to any datatype.  The input and
output vectors may be the same, without loss of data.  The input and
output datatypes may be the same, in which case no conversion is
performed.


.ks
.nf
procedure impak$t (a, b, npix, dtype)

begin
	switch (dtype) {
	case TY_USHORT:
	    call acht$tu (a, b, npix)
	case TY_SHORT:
	    call acht$ts (a, b, npix)
	case TY_INT:
	    call acht$ti (a, b, npix)
	case TY_LONG:
	    call acht$tl (a, b, npix)
	case TY_REAL:
	    call acht$tr (a, b, npix)
	case TY_DOUBLE:
	    call acht$td (a, b, npix)
	case TY_COMPLEX:
	    call acht$tx (a, b, npix)
	default:
	    call syserr (unknown_datatype_in_imagefile)
	}
end
.fi
.ke


.sh
Data Structure Management

    When an image is mapped, buffer space is allocated for a copy of
the image header, and for the image descriptor (used by IMIO while an
image is mapped).  When the first i/o transfer is done on an image,
either an input or an output data buffer will be created.  The size of
this buffer is governed by the size of the transfer, and by the datatypes
of the pixels on disk and in program space.

If a new image is being written, the pixel storage file is created at
the time of the first PUTPIX operation.  The physical characteristics
of the new image, defined by the image header of the new image, are
unalterable once the first i/o operation has occurred.  Accordingly,
the number of dimensions, length of the dimensions, datatype of the
pixels on disk, and so on must be set (in the image header structure)
before writing to the new image.

The only exception to this rule may be the addition of new lines to a
two dimensional image stored in line storage mode, or the addition of
new bands to a multiband image stored in band sequential (noninterlaced)
mode.  It is not always possible to modify the dimensions or size of
an existing image.

It is possible to preallocate space for an image (using FALOC).  This
may result in a more nearly contiguous file, and may make writing a
new image slightly more efficient, since it will not be necessary
to write blocks of zeros in IMPGS?.  Preallocation will occur
automatically in systems where it is desirable.

.sh
Pixel Buffer Management

    There may be any number of input buffers per image, but only a single
output buffer.  By default there is only a single input buffer.  The input
and output buffers are distinct: the same buffer is never used for both
input and output (unlike FIO).

The size of a buffer may range from one pixel, to the entire image (or
larger if boundary extension is in use).  If multiple buffers are in use,
all buffers do not have to be the same size.  The size of a buffer may
vary from one GETPIX or PUTPIX call to the next.

If multiple input buffers are in use, buffers are allocated in a strictly
round robin fashion, one per GETPIX call.  Several buffers may contain
data from the same part of the image.  Once the desired number of buffers
have been filled, a buffer "goes away" with each subsequent GETPIX call.


IMGIBF gets an input buffer.  When called to get a line or section,
the vectors VS and VE specify the subsection to be extracted.
This information is saved in the buffer descriptor, along with the
datatype of the pixels and the dimension of the section.

When IMGIBF is called to get a list of pixels, VS and VE would have to be
replaced by a set of NPIX such vectors, to fully specify the section.
It is impractical to save this much information in the buffer descriptor,
so when creating a buffer to contain a list of pixels, VS and VE are faked
to indicate a one dimensional section of the appropriate size.




.ks
.nf
pointer procedure imgibf (imdes, vs, ve, dtype)

imdes	image descriptor
vs,ve	define the number of pixels to be buffered
dtype	the datatype of the pixels in the program

begin
	# If first input transfer, allocate and initialize array of
	# input buffer descriptors.

	if (imdes.ibdes == NULL) {
	    call imopsf (imdes)
	    call calloc (imdes.ibdes, LEN_BDES * imdes.nbufs, TY_STRUCT)
	}

	# Compute pointer to the next input buffer descriptor.
	# Increment NGET, the count of the number of GETPIX calls.

	bdes = &imdes.ibdes [mod (imdes.nget, imdes.nbuf) + 1]
	imdes.nget += 1

	# Compute the size of the buffer needed.  Check buffer
	# descriptor to see if the old buffer is the right size.
	# If so, use it, otherwise make a new one.

	nchars = imcssz (imdes, vs, ve, dtype)

	if (nchars < bdes.bufsize)
	    call realloc (bdes.bufptr, nchars, TY_CHAR)
	else if (nchars > bdes.bufsize) {
	    call mfree (bdes.bufptr, TY_CHAR)
	    call malloc (bdes.bufptr, nchars, TY_CHAR)
	}

	# Save section coordinates, datatype in buffer descriptor, and
	# return buffer pointer to calling program.

	bdes.bufsize = nchars
	bdes.dtype = dtype
	bdes.npix = totpix

	do i = 1, imdes.ndim {
	    bdes.vs[i] = vs[i]
	    bdes.ve[i] = ve[i]
	}

	return (coerce (bdes.bufptr, TY_CHAR, dtype)
end
.fi
.ke




.ks
.nf
pointer procedure imgobf (imdes, vs, ve, dtype)

imdes	image descriptor
vs,ve	define the number of pixels to be buffered
dtype	the datatype of the pixels in the program

begin
	# If first write, and if new image, create pixel storage file,
	# otherwise open pixel storage file.  Allocate and initialize
	# output buffer descriptor.

	if (imdes.obdes == NULL) {
	    call imopsf (imdes)
	    call calloc (imdes.obdes, LEN_BDES, TY_STRUCT)
	}

	bdes = imdes.obdes

	# Compute the size of buffer needed.  Add a few extra chars
	# to guarantee that there won't be a memory violation when
	# writing a full physical length line.

	nchars = imcssz (imdes, vs, ve, dtype) +
	(imdes.physlen[1] - imdes.len[1]) * sizeof (imdes.pixtype)

	if (nchars < bdes.bufsize)
	    call realloc (bdes.bufptr, nchars, TY_CHAR)
	else if (nchars > bdes.bufsize) {
	    call mfree (bdes.bufptr, TY_CHAR)
	    call malloc (bdes.bufptr, nchars, TY_CHAR)
	}

	# Save section coordinates, datatype of pixels in buffer
	# descriptor, and return buffer pointer to calling program.

	bdes.bufsize = nchars
	bdes.dtype = dtype
	bdes.npix = totpix

	do i = 1, imdes.ndim {
	    bdes.vs[i] = vs[i]
	    bdes.ve[i] = ve[i]
	}

	return (coerce (bdes.bufptr, TY_CHAR, dtype)
end
.fi
.ke



Given two vectors describing the starting and ending coordinates
of an image section, compute and return the amount of storage needed
to contain the section.  Sufficient storage must be allocated to
hold the largest datatype pixels which will occupy the buffer.



.ks
.nf
long procedure imcssz (imdes, vs, ve, dtype)

begin
	pix_size = max (sizeof(imdes.pixtype), sizeof(dtype))
	npix = 0

	do i = 1, imdes.ndim
	    if (vs[i] <= ve[i])
		npix *= ve[i] - vs[i] + 1
	    else
		npix *= vs[i] - ve[i] + 1

	return (npix * pix_size)
end
.fi
.ke


.sh
Mapping and unmapping Image Structures

    An imagefile must be "mapped" to an image structure before the
structure can be accessed.  The map operation associates a file with
a defined structure.

The IMMAP procedure must allocate a buffer for the image header
structure, and for the image descriptor structure.  If an existing
imagefile is being mapped, the header is copied into memory from
the imagefile.  If a new image is being mapped, the header structure
is allocated and initialized.

If an image is being mapped as a "new copy", a new header
structure is created which is a copy of the header of an image which
has already been mapped.  The entire image header, including any
application specific fields, is copied.

After copying an image header for a NEW_COPY image, the header field
containing the name of the pixel storage file is cleared.  A "new copy"
image structure does not inherit any pixels.  Any similar substructures
which describe the attributes of the pixels (i.e., the blank pixel
list, the histogram) must also be initialized.

Note that the "image descriptor" buffer allocated below actually 
contains the image descriptor, followed by the standard image header
(at offset IMHDR_OFF), followed by any user fields.  If an existing
image structure is being mapped, the caller supplies the length of
the user area of the header as the third argument to IMMAP.

IMMAP returns a pointer to the first field of the standard header
as the function value.  The image descriptor is invisible to the
calling program.



.ks
.nf
pointer procedure immap (fname, mode, hdr_arg)

begin
	# Add code here to handle section suffixes in imagefile
	# name strings (e.g. "image[*,5]").

	# Open image header file.
	hfd = open (fname, mmap[mode], BINARY_FILE)

	# Allocate buffer for image descriptor/image header.  Note
	# the dual use of the HDR_ARG argument.

	if (mode == NEW_COPY)
	    sz_imhdr = hdr_arg.sz_imhdr
	else
	    sz_imhdr = (LEN_IMHDR + int(hdr_arg)) * SZ_STRUCT

	call calloc (imdes, SZ_IMDES + sz_imhdr, TY_STRUCT)
	imhdr = imdes + IMHDR_OFF

	[initialize the image descriptor, including the default
	image section (optionally set by user with suffix above).]

	# Initialize the mode dependent fields of the image header.
	switch (mode) {
	case NEW_COPY:
	    call im_init_newcopy (imdes, hdr_arg)
	case NEW_IMAGE:
	    [initialize the image header]
	default:
	    call seek (hfd, BOFL)
	    n = read (hfd, Memi[imhdr], sz_imhdr)
	    if (n < SZ_IMHDR || strne (IM_MAGIC(imhdr), "imhdr")) {
		call mfree (imdes)
		call imerr (fname, file_not_an_imagefile)
	    } else if (mode == READ_ONLY)
		call close (hfd)
	}

	[initialize those fields of the image header which are not
	dependent on the mode of access.]

	return (imhdr_pointer)
end
.fi
.ke




.ks
.nf
procedure imunmap (imhdr)

begin
	imdes = imhdr - IMHDR_OFF

	# Flush the output buffer, if necessary.
	call imflush (imhdr)

	# Append the bad pixel list.
	if (the bad pixel list has been modified) {
	    if (file_size < blist_offset)
		[write out zeros until the offset of the bad pixel
		list is reached]
	    [append the bad pixel list]
	    [free buffer space used by bad pixel list]
	}

	call close (imdes.pfd)

	# Update the image header, if necessary (count of bad pixels,
	# minimum and maximum pixel values, etc.).

	if (imdes.update == YES) {
	    if (no write permission on image)
		call imerr (imname, cannot_update_imhdr)
	    call imuphdr (imdes)
	    call close (imdes.hfd)
	}

	# Free buffer space.
	for (i=1;  i <= imdes.nbufs;  i=i+1)
	    call mfree (imdes.ibdes[i].bufptr, TY_CHAR)
	call mfree (imdes.obdes.bufptr, TY_CHAR)
	call mfree (imdes, TY_STRUCT)
end
.fi
.ke


IMFLUSH indirectly references a typed flush procedure, the entry point
address of which was saved in the image descriptor at the time of the
last IMPGS? call.  The problem here is that IMFLUSH must work properly
regardless of the data type of the pixels in the output buffer.  To
ensure this, and to avoid having to link in the full matrix of 48 type
conversion routines, we call LOC in the put-section procedure to reference
the appropriate typed flush routine.



.ks
.nf
procedure imflush (imhdr)

begin
	if (imdes.flush == YES)
	    call zcall1 (imdes.flush_epa, imdes)
end
.fi
.ke



The following procedure is called by the IMGOBF and IMGIBF routines
to open the pixel storage file, during the first PUTPIX operation on
a file.


.ks
.nf
procedure imopsf (imdes)

begin
	switch (imdes.mode) {
	case READ_ONLY, READ_WRITE, WRITE_ONLY, APPEND:
	    imdes.pfd = open (imdes.pixfile, imdes.mode, BINARY_FILE)
	    if (read (imdes.pfd, pix_hdr, SZ_PIXHDR) < SZ_IMMAGIC)
		call imerr (imname, cannot_read_pixel_storage_file)
	    else if (strne (pix_hdr.im_magic, "impix"))
		call imerr (imname, not_a_pixel_storage_file)

	case NEW_COPY, NEW_FILE, TEMP_FILE:
	    # Get the block size for device "imdir$", and initialize
	    # the physical dimensions of the image, and the absolute
	    # file offsets of the major components of the pixel storage
	    # file.

	    dev_block_size = fdevblk ("imdir$")
	    [initialize im_physlen, im_pixels, im_hgmoff fields
	    in image header structure]

	    # Open the new pixel storage file (preallocate space if
	    # enabled on local system).  Call FADDLN to tell FIO that
	    # the pixfile is subordinate to the header file (for delete,
	    # copy, etc.).  Save the physical pathname of the pixfile
	    # in the image header, in case "imdir$" changes.

	    call mktemp ("imdir$im", temp, SZ_FNAME)
	    call fpathname (temp, imhdr.pixfile, SZ_PATHNAME)

	    if (preallocation of imagefiles is enabled)
		call falloc (imhdr.pixfile, sz_pixfile)
	    imdes.pfd = open (imdes.pixfile, NEW_FILE, BINARY_FILE)
	    call faddln (imdes.imname, imdes.pixfile)

	    # Write small header into pixel storage file.  Allows
	    # detection of headerless pixfiles, and reconstruction
	    # of header if it gets lost.

	    [write pix_hdr header structure to pixel storage file]

	default:
	    call imerr (imname, illegal_access_mode)
	}
end
.fi
.ke


.sh
Data Structures

    An imagefile consists of two separate files.  The first file contains
the image header.  In the prototype, there may be only a single header per
header file.  The header consists of the standard image header, followed
by an arbitrary number of user defined fields.

The standard part of the image header has a fixed structure.  All the variable
size components of an image are stored in the pixel storage file.  The
name of the pixel storage file, and the offsets to the various components
of the image, are stored in the image header.  The name of the image header
file is in turn stored in the header area of the pixel storage file,
making it possible to detect headerless images.

The pixel storage file contains a small header, followed by the pixels
(aligned on a block boundary), optionally followed by a fixed size
histogram, and a variable size bad pixel list.


.ks
.nf
		   Structure of an Imagefile

		---------            ---------
		    |       <----        |
		 standard  ---->       header 
		  image                  |
		  header               PIXELS
		    |                    |
		   user              histogram      (optional)
		  fields                 |
		    |                   bad
		   \|/                 pixel        (optional)
		----------              list
		                         |
		                        \|/
				     ---------
.fi
.ke


The image header file, which is small, will reside in the users own
directory.  The pixel storage file is generated and manipulated 
transparently to the applications program and the user, and resides
in the temporary files system, in the logical directory "imdir$".

Storing the parts of an image in two separate files does cause problems.
The standard file operators, like DELETE, COPY, RENAME, and so on,
either cannot be used to manipulate imagefiles, or must know about
imagefiles.

To solve this problem, without requiring FIO to know anything about IMIO
or VSIO data structures, two operators will be added to FIO.  The first
will tell FIO that file 'A' has a subordinate file 'B' associated with
it.  Any number of subordinate files may be associated with a file.
The information will be maintained as a list of file names in an invisible
text file in the same directory as file 'A'.

The second operator will delete the link to a subordinate file.  The FIO
procedures DELETE and RENAME will check for subordinate files, as will CL
utilities like COPY.

.sh
The Standard Image Header

    The standard fields of an image header describe the physical
characteristics of the image (required to access the pixels), plus
a few derived or historic attributes, which are commonly associated
with images as used in scientific applications.


.ks
.nf
struct imhdr {
	char	im_magic[5]		# contains the string "imhdr"
	long	im_hdrlen		# length of image header
	int	im_pixtype		# datatype of the pixels
	int	im_ndim			# number of dimensions
	long	im_len[MAXDIM]		# length of the dimensions
	long	im_physlen[MAXDIM]	# physical length (as stored)
	long	im_pixels		# offset of the pixels
	long	im_hgmoff		# offset of hgm pixels
	long	im_blist		# offset of bad pixel list
	long	im_szblist		# size of bad pixel list
	long	im_nbpix		# number of bad pixels
	long	im_cdate		# date of image creation
	long	im_mdate		# date of last modify
	real	im_max			# max pixel value
	real	im_min			# min pixel value
	struct	histogram im_hgm	# histogram descriptor
	struct	coord_tran im_coord	# coordinate transformations
	char	im_pixfile[SZ_PATHNAME]	# name of pixel storage file
	char	im_name[SZ_IMNAME]	# image name string
	char	im_history[SZ_IMHIST]	# history comment string
}
.fi
.ke



The histogram structure, if valid, tells where in the pixel storage file
the histogram is stored, and in addition summarizes the principal
attributes of the histogram.  All of these quantities are directly
calculable, except for the last three.  The modal value is determined
by centering on the (major) peak of the histogram.  LCUT and HCUT define
an area, centered on the modal value, which contains a certain fraction
of the total integral.


.ks
.nf
struct histogram {
	int	hgm_valid		# YES if histogram is valid
	int	hgm_len			# number of bins in hgm
	long	hgm_npix		# npix used to compute hgm
	real	hgm_min			# min hgm value
	real	hgm_max			# max hgm value
	real	hgm_integral		# integral of hgm
	real	hgm_mean		# mean value
	real	hgm_variance		# variance about mean
	real	hgm_skewness		# skewness of hgm
	real	hgm_mode		# modal value of hgm
	real	hgm_lcut		# low cutoff value
	real	hgm_hcut		# high cutoff value
}
.fi
.ke



The coordinate transformation descriptor is used to map pixel coordinates
to some user defined virtual coordinate system, (useful when displaying the
contents of an image).  For lack of a significantly better scheme, we have
simply adopted the descriptor defined by the FITS standard.


.ks
.nf
struct coord_tran {
	real	im_bscale		# pixval scale factor
	real	im_bzero		# pixval offset
	real	im_crval[MAXDIM]	# value at pixel
	real	im_crpix[MAXDIM]	# index of pixel
	real	im_cdelt[MAXDIM]	# increment along axis
	real	im_crota[MAXDIM]	# rotation angle
	char	im_bunit[SZ_BUNIT]	# pixval ("brightness") units
	char	im_ctype[SZ_IMCTYPE,MAXDIM]	# coord units
}
.fi
.ke



The image and buffer descriptors are used internally by IMIO while
doing i/o on a mapped image.  The image descriptor structure is
allocated immediately before the image header, is transparent to the
applications program, and is used to maintain runtime data, which
does not belong in the image header.


.ks
.nf
struct image_descriptor {
	long	file_size			# size of pixfile
	long	nget				# number getpix calls
	int	nbufs				# number of in buffers
	int	flush				# flush outbuf?
	int	update				# update header?
	int	pfd				# pixfile fd
	int	hfd				# header file fd
	int	flush_epa			# epa of imfls? routine
	struct	buffer_descriptor *ibdes	# input bufdes
	struct	buffer_descriptor *obdes	# output bufdes
	char	imname[SZ_FNAME]		# imagefile name
}
.fi
.ke



.ks
.nf
struct buffer_descriptor {
	char	*bufptr			# buffer pointer
	int	dtype			# datatype of pixels
	long	npix			# number of pixels in buf
	long	bufsize			# buffer size, chars
	long	vs[MAXDIM]		# section start vector
	long	ve[MAXDIM]		# section end vector
}
.fi
.ke