C************************************************************************ C * C Some useful documentation for: * C * C IMAGE Analysis and file format Programs & Routines * C * C * C Last Update: 11-OCT-1985 VAX/VMS * C * C * C************************************************************************ Main IMAGE Programs =================== 1. BOXIM Circular or Polygonal Box and float image (JMS) 2. DECON2D 2-D Iterative, constrained deconvolution (DA) 3. ENHANCE Bandpass filter enhancement (DA) 4. FFTRANS 2-D Foward/Reverse Fourier transform (DA) 5. HISTO Calculates Density Histogram (DA) 6. IMCON Converts film scans on CDS disk to image format (DA) 7. INTERPO Generalized 2-D interpolation,skewing,rotation,etc (DA) 8. LABEL General utility program - does a few nice things (DA) 9. MULTIFFT Fast FFT for stack of images, useful for 3D work (DA) 10. ONEBIT Single bit gray scale toning program (DA) 11. TAPECON Converts film scans on tape to image format (DA) 12. THREED Three-dimensional Surface contour plot (DA) 13. THREEDFFT Three-dimensional FFT program (DA) 14. TONE Does pseudo-gray scale plotting on Trilog (DA) 15. TRMASK Mask transform for "optical" filtering (RAC) 16. TRNOUT Amp and phase output of transform (RAC) 17. TWOFILE Does simple math on 2 IMAGE files (RAC/RH) 18. IMEDIT General editing program (JMS) 19. AEDDSP Raster Graphics display program (JMS) Higher-Level IMAGE PROCESSING subroutines ========================================= 1. INTERP Generalized 2-D interpolation from matrix 2. FILTER Applies a contrast-transfer-function filter 3. TODFFT In-place Foward/Backward 2-D FFT routine +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Linking Files: Two link procedures are provided for linking in the variuos IMAGE subroutines. They are: IMLINK links in all IMAGE subroutines PIMLINK links in all IMAGE subroutines & the PLOT subroutines +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 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 ppropriate 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.