5. Higher-Level IMAGE File subroutines

	These routine are designed to facilitate the rapid setup and
manipulation of image-format files. Either Sequential access or
Direct access I/O operations may be performed at any time.These routines
will now also cope with map-format files.
	In general, the X-Y origin is taken as 0,0 being in the
lower-left corner of the image AND the first data point in the file
(normally corresponding to array element 1,1).

			Top of Image		 1,NY	  Array    NX,NY
		^ !				   ^ !
		! !				   ! !
		! !				   ! !
		y !				   y !
		  !_____________   x-->              !_______________  x-->
		0,0				    1,1             NX,1




	The convention for FOURIER TRANSFORMS is that the transform of
an image of dimensions NX x NY yields a transform of NX/2+1 x NY
COMPLEX values. The origin of Fourier space is located at coordinates
0,NY/2 (disk coordinates, which would normally be 1,NY/2+1 in the FORTRAN
array). In reciprocal lattice units:
   X goes from 0 --> 0.5  and Y goes from -0.5 ---> (.5 - deltaY)





	Upto 5 image files may be open at any one time!!
             -

	All higher-level image routines begin with the letter I.
With the exception on the OPEN/CLOSE and Positioning routines a standard
naming convention has been established.
	The second 2 letters are chosen from the following.
	RD   =  Read
	WR   =  Write
	CL   =  Calculate
	CR   =  Create
	AL   =  Alter
	TR   =  Transfer
	RT   =  Return information

	The last 3 letters are chosen from the following:
	CDN  =  Density limits (Complex numbers, ie uses Modulus)
	CEL  =  unit cell paramters
	CON  =	conversion to reals
	DEN  =  Density limits
	EXT  =  Extra information ("unused" header slots)
	HDR  =  Header
	LAB  =  Labels
	MOD  =  Mode
	ORG  =	Origin
        SAM  =  Sampling information
 	SIZ  =  Size
        SYM  =  Symmetry information
	LIN  =  Line
	SEC  =  Section
	PAL  =  Part of Line
	PAS  =  Part of Section


	Specifications for higher-level image I/O routines:

File Set-Up Routines:
---------------------

CALL IMOPEN(ISTREAM,NAME,ATBUTE)		   Opens file NAME on ISTREAM

CALL IMCLOSE(ISTREAM)				   Closes file

CALL IRDHDR(ISTREAM,NXYZ,MXYZ,MODE,DMIN,DMAX,DMEAN)
				 		   Read  header on input file

CALL IWRHDR(ISTREAM,TITLE,NTFLAG,DMIN,DMAX,DMEAN)
						   Write header to output file

CALL ITRHDR(ISTREAM,JSTREAM)			   Transfer header from JSTREAM
						   to ISTREAM (does not write!)

CALL ITRLAB(ISTREAM,JSTREAM)			   Transfer labels from JSTREAM
						   to ISTREAM (does not write!)

CALL ITRCEL(ISTREAM,JSTREAM)			   Transfer CELL parmas  from
						   JSTREAM to ISTREAM (no write!)

CALL ICRHDR(ISTREAM,NXYZ,MXYZ,MODE,LABELS,NL)	   Create NEW header. The header
						   is NOT written out. You must
						   do a IWRHDR.
						   In general, it is advised that
						   one use ITRHDR followed by the
						   appropriate alter calls such as
						   CALL IALSIZ(....)   etc.
						   This is preferred because all
						   information is transferred by
						   the transfer call.

CALL IALCEL(ISTREAM,CELL)			   Alter unit cell paramters

CALL IALCON(ISTREAM,FLAG)			   Alter conversion to reals.
						   By default, all data is passed
						   to the user as REALS or COMPLEX
						   REALS, independent of storage mode
						   on disk. This call allows this
						   to be overridden.
						   This should be used with CAUTION!!!
						   FLAG = .TRUE.    conversion to REALS
						   FLAG = .FALSE.    NO conversion!!!

CALL IALEXT(ISTREAM,EXTRA,ISTART,NEXTRA)	   Alters  info in "unused"
						   slot in header, starting
						   at position ISTART. 
						   NEXTRA words are altered.

CALL IALLAB(ISTREAM,LABELS,NL)			   Alters NL labels in header

CALL IALMOD(ISTREAM,MODE)			   Alter MODE on existing header

CALL IALORG(ISTREAM,XORIGIN,YORIGIN)		   Alter XY origin information

CALL IALSAM(ISTREAM,MXYZ)                          Alter sampling information

CALL IALSIZ(ISTREAM,NXYZ,NXYZST)		   Alter SIZE on existing header
						   Note, the NXYZST is for your
						   use ONLY. It is stored in the
						   file header for interfacing with
						   the X-ray programs, but all calls
						   within the image package, are
						   always taken relative to the
						   start of each line, or section.

CALL IALSYM(ISTREAM,KSPG,KBS)                      Alters symmetry parameters
                                                   KSPG is space group number
                                                   KBS is number of bytes of
                                                   symmetry data

CALL IALUVW(ISTREAM,IUVW)                          Alters matrix to permute
                                                   cell  dimensions.



File Positioning Routine:
-------------------------

CALL IMPOSN(ISTREAM,NZ,NY)			    Move to section NZ, line NY
						    Default convetions are all
						    numbers start at 0 !!!!


Line Read/Write Routines:
-------------------------

	In all cases, ARRAY is a REAL or COMPLEX REAL data array.
	All of these routines convert from/to Integer*2 as required.


CALL IRDLIN(ISTREAM,ARRAY,*LINE)		    Read line  (NX points)

CALL IWRLIN(ISTREAM,ARRAY)			    Write line (NX points)


CALL IRDPAL(ISTREAM,ARRAY,NX1,NX2,*LINE)	    Read  part line (NX1 - NX2)
						    Data is always loaded into
						    the FIRST element of ARRAY.
						    After READ, pointer is at
						    Start of next line.

CALL IWRPAL(ISTREAM,ARRAY,NX1,NX2)		    Write part line (NX1 - NX2)
						    from selected region in
						    core onto disk.



Section Read/Write Routines:
----------------------------

	In all cases, ARRAY is a REAL or COMPLEX REAL data array.
	All of these routines convert from/to Integer*2 as required.


CALL IRDSEC(ISTREAM,ARRAY,*LINE)		    Read  section 

CALL IWRSEC(ISTREAM,ARRAY)			    Write section 


CALL IRDPAS(ISTREAM,ARRAY,MX,MY,NX1,NX2,NY1,NY2,*LINE)
						    Read  part of section
						    After READ, pointer is at
						    Start of next section.

CALL IWRPAS(ISTREAM,ARRAY,MX,MY,NX1,NX2,NY1,NY2)    Write  part of section




Other Useful Routines:
----------------------


CALL ICLCDN(ARRAY,MX,MY,NX1,NX2,NY1,NY2,DMIN,DMAX,DMEAN)   (Mod of Complex vals)
CALL ICLDEN(ARRAY,MX,MY,NX1,NX2,NY1,NY2,DMIN,DMAX,DMEAN)   (Real numbers)
						    Calculates the MIN/
						    MAX, & MEAN densities
						    from the selected portion
						    of ARRAY (assumed to be
						    image!!). NOTE: Here and
						    only here does the counting
						    start from 1.
CALL ICLLIM(ISTREAM,IXYZMIN,IXYZMAX,NXYZ)
						    Prompts the user to supply
						    area limit (0,0 lower left)
						    and returns pixel limits
						    # pixels, and user limits

IUNIT = IMUNIT(ISTREAM)				    Returns IUNIT which is
						    compatible with the
						    LOW-LEVEL routines.

CALL IRTCEL(ISTREAM,CELL)			    returns CELL(6)

CALL IRTEXT(ISTREAM,EXTRA,ISTART,NEXTRA)	    Returns NEXTRA words extra
						    slot in header, starting
						    at position ISTART. There
						    are 29 available words.
						   

CALL IRTLAB(ISTREAM,LABELS,NL)			    Returns LABELS(20,10)
						    number of labels NL.

CALL IRTORG(ISTREAM,XORIGIN,YORIGIN)		    Returns XY origin information

CALL IRTSAM(ISTREAM,MXYZ)                           Returns sampling information

CALL IRTSIZ(ISTREAM,NXYZ,MXYZ,NXYZST)		    Returns SIZE info

CALL IRTSYM(ISTREAM,KSPG,KBS)                       Returns symmetry parameters
                                                    KSPG is space group number
                                                    KBS is number of bytes of
                                                    symmetry data

CALL IRTUVW(ISTREAM,IUVW)                           Returns matrix to permute
                                                    cell  dimensions.



Variable Definitions:		(ALL variables are INTEGER*4 or REAL!!)
---------------------


ARRAY:		A storage location for data transfer. NOTE ARRAY is either
		REAL*4 or COMPLEX*8 !!!!!
		
ATBUTE:		File attribute specification. One of the following character
		strings must be given:  'NEW'  'OLD'  'RO'  or  'SCRATCH'

DMIN/DMAX/	The minimum, maximum, & mean density values for this image.
DMEAN:

EXTRA(29)	An array (up to 29 long) or a storage location for holding
		the values for the EXTRA info slot in the header.

ISTART:		A number between 1-29 to select the first element of the
		EXTRA info to transfer.

ISTREAM/	A number between 1 and 12 used to select which file
JSTREAM:	to use for READ/WRITE operations. A maximum of 5
		files can be active at any one time.

IXYZMIN(3)/	Returned lower & upper pixel limits that correspond to user
IXYZMAX(3):	selected input range. (pixels have 0,0 at bottom left)

MODE:		Defines data structure on disk:
		0 = INTEGER*1	 IMAGE note:values between 127 & 255
                                       stored as -128 to -1 but returned
                                       as their original values.
		1 = INTEGER*2    IMAGE
		2 = REAL*4       IMAGE
		3 = INTEGER*2    FOURIER TRANSFORM
		4 = REAL*4       FOURIER TRANSFORM

MX/MY:		Dimensions of ARRAY. If transferred data size is smaller
		than MX,MY the remainder of the space will be set to 0.
		Note: MX correspons to the number of REAL numbers in the
		fast dimension of ARRAY. If MODE = 3 or 4 (Fourier
		Transform) MX MUST be multiplied by 2!!!

MXYZ(3):	Specifies the number of columns, rows, & sections in the
		entire "unit cell"  (can be identical to NXYZ).

LABELS(20,N)	N = 1 - 10. This is a way to ititialize more than
		one text label when creating a new header. LABELS(20)
		is also permitted. Each label is 80 characters long (A4).

NAME:		A character string specifying either the FILENAME or
		a LOGICAL name to associate with a given stream.

NEXTRA:		A number bewteen 1-29 to select the number of EXTRA
		value to transfer.

NL:		The number of LABELS being initialized (see LABELS, above).

NTFLAG:		-1 no titles added to list.
		 0 to use TITLE as sole title on file (overwrites old title).
		 1 to add TITLE to end of list. 
		 2 to add at top, pushing any other labels down.

NX1/NX2:	Beginning & ending COLUMN numbers for data transfer.
		On reading these numbers are relative to NXTZST(1).
		For Fourier Transforms, these are taken as Complex Indicies!!!

NXYZ(3):	Specifies the number of columns, rows, & sections in the
		current file (ie. fastest -> slowest changing).

NXYZST(3):	Specifies the starting column, row and section number.
		Note, the NXYZST is for your use ONLY. It is stored in the
		file header for interfacing with the X-ray programs, but all
		calls within the image package, are always taken relative to
		the start of each line, or section. The start is ALWAYS
		denoted by 0.

NY:		Line number for positioning pointer. This value
		is relative to NXYST(2)

NY1/NY2:	Beginning & ending ROW    numbers for data transfer.
		On reading these numbers are relative to NXTZST(2).

NZ:		Section number for positioning pointer. This value
		is relative to NXYST(3)

TITLE(20)	80 character title. Written as dictated by NTFLAG.

XORIGIN/	The X & Y image origin (generally used for relating
YORIGIN:	phase origins).

*LINE		LINE is a statement number to branch to on an
		END-OF-FILE error. Example:   *99



		Map/Image Header Format
		-----------------------

	Length = 1024 bytes, orgainized as 56 LONG words followed
by space for 10 80 byte text labels.

 1	NX		# of Columns	(fastest changing in map)
 2	NY		# of Rows
 3	NZ		# of Sections 	(slowest changing in map)
 4	MODE		Data type
			  0 = Image     stored as Integer*1
			  1 = Image	stored as Integer*2
			  2 = Image	stored as Reals
			  3 = Transform	stored as Complex Integer*2
			  4 = Transform	stored as Complex Reals

 5	NXSTART		Number of first COLUMN  in map (Default = 0)
 6	NYSTART		Number of first ROW     in map      "
 7	NZSTART		Number of first SECTION in map      "
 8	MX		Number of intervals along X
 9	MY		Number of intervals along Y
10	MZ		Number of intervals along Z
11	X length	Cell Dimensions (Angstroms)
12	Y length		     "
13	Z length		     "
14	Alpha		Cell Angles     (Degrees)
15	Beta		             "
16	Gamma		             "
17	MAPC		Which axis corresponds to Columns  (1,2,3 for X,Y,Z)
18	MAPR		Which axis corresponds to Rows     (1,2,3 for X,Y,Z)
19	MAPS		Which axis corresponds to Sections (1,2,3 for X,Y,Z)
20	AMIN		Minimum density value
21	AMAX		Maximum density value
22	AMEAN		Mean    density value    (Average)
23	ISPG		Space group number       (0 for images)
24	NSYMBT		Number of bytes used for storing symmetry operators
25	EXTRA		Extra, user defined storage space. 29 words max.
.          "
.          "
.          "   (all set to zero by default)
.          "
53	   "
54	XORIGIN		X origin
55	YORIGIN		Y origin
56	NLABL		Number of labels being used
57-256  LABEL(20,10)	10  80 character text labels (ie. A4 format)

Symmetry records follow - if any - stored as text as in International
Tables, operators separated by * and grouped into 'lines' of 80
characters (ie. symmetry operators do not cross the ends of the
80-character 'lines' and the 'lines' do not terminate in a *).

		Data records follow.




	LOW-LEVEL Random-Access Subroutines.
	====================================


	The LOW-LEVEL set of FORTRAN subroutines for doing
	either sequential or random access disk I/O with
	with variable record lengths are indicated below.
	The files are actually written as fixed-record
	direct-access files, but this is transparent to
	the user.

Note: 	The use of fixed-block I/O will, in general, result
	in a file slightly larger than the actual amount of data written.
	As a result, END-OF-DATA may NOT be the same as END-OF-FILE.
	if END-OF-FILE detection is important, the user should set
	his/her own flag.

Note: 	Only 10 files may be opened simultaneously!!!!
		   -

	the calls provided are:

	CALL QOPEN(IUNIT,NAME,ATTRIBUTE)		   ;open file
	CALL QCLOSE(IUNIT)				   ;close file
	CALL QREAD(IUNIT,ARRAY,NBYTES,IER)		   ;read nbytes
	CALL QWRITE(IUNIT,ARRAY,NBYTES)			   ;write nbytes
	CALL QSEEK(IUNIT,IRECORD,IELEMENT,IRECLENGTH)	   ;move to irec,iel
	CALL QBACK(IUNIT,IRECLENGTH)			   ;backspace 1 record
	CALL QSKIP(IUNIT,IRECLENGTH)			   ;skip 1 record
	CALL QINQUIRE(IUNIT,NAME,LENGTH)		   ;get full name & len
	CALL QLOCATE(IUNIT,LOCATION)			   :rtn disk location

Note:	QSEEK calculates the location as follows:
	LOCATION = (IRECORD - 1)*IRECLENGTH + IELEMENT

Note:	As in FORTRAN, addressing begins at 1 for BOTH record & element

	Variable Definitions:   (ALL variables are INTEGER*4 or REAL!!!)
	---------------------

	IUNIT	   = Variable used to contain channel # (SET by QOPEN!!!)
	NAME	   = either a LOGICAL or FILE name to be associated with unit
	ATTRIBUTE  = one of the following: 'NEW' 'OLD' 'RO' 'SCRATCH'
	ARRAY	   = starting location for data storage in core
	NBYTES     = number of BYTES to transfer
	IER	   = error flag (0 = no error) else # of bytes transferred
	IRECORD	   = desired record #     (starts @ 1)
	IELEMENT   = desired element # within record (bytes)   (starts @ 1)
	IRECLENGTH = record length in bytes
	LENGTH	   = returned file length in 512 byte BLOCKS
	LOCATION   = returned disk pointer location in bytes  (starts @ 1)


	INTERNAL CALLS MADE TO Q$READ,Q$WRITE,Q$OPEN,Q$CLOSE,ZERO
	QINQUIRE is actually in the BLOCKIO Macro package.