/* README August 1997 APIP: 1.7 Astrophysics Pyramid Image Processing APIP is Copyright (C) 1993 - 1998 by California Institute of Technology. All Rights Reserved. Developed under contract to JPL, NASA ADP contract NRA 92-OSSA-15 And Applied Information Systems NRA-96-OSS-10 by Dr. Charles H. Anderson in collaboration with Dr. William D. Langer, JPL/CIT. Dr. Charles H. Anderson Dept. of Anatomy and Neuroscience Box 8108 Washington University School of Medicine 660 South Euclid Ave. St. Louis, MO 63110 cha@shifter.wustl.edu -----------------------------------------------------------------------*/ The Astrophysics Pyramid Image Processing Package provide multiresolution image processing functions, along with several basic image processing functions and display utilities that run in a UNIX X-windows environment. The functions operate on FITS image file formats and an older, more primitive format (described below), that was developed at JPL in the Image Analysis Systems group under Jerry Solomon's direction. Limited support is also provided for conversion of 8 bit TIFF image file format and Postscript files. Installation: Put the file apip1.1.tar.Z in a directory where APIP is to be installed. Uncompress and install the subdirectories and files using the UNIX command. uncompress -c apip1.1.tar.Z | tar xvf - You can rename the directory apip1.1 to apip, or anything you wish. Go to this directory and copy the appropriate Makefile.xxx to Makefile. The choices are: Makefile.sun SUN OS Makefile.solaris SUN Solaris Makefile.hp HP Makefile.sgi SGI Makefile.gcc GCC compiler support (tested on a SUN) Makefile.bor Borland compiler 4.0 or later Makefile.vc4 Microsoft Visual C 4.0. (Use nmake) Typing `make -i install' will start the installation. Many warnings are created, especially in libtiff. These have never proven to be serious. Errors should be reported to cha@shifter.wustl.edu. To uninstall type `make -i clean'. CAUTION: With HP's you need to go into each of the apip subdirectories where there are executables and insert full path names in each Makefile.hp manually. These are apip/mains, apip/tiff, apip/wavelets, apip/display, apip/cluster, and apip/ps. The display routines need access to XWindow routines, X11R4. The include files normally reside in /usr/include/X11R4. ----------------------------------------------------------------- Environment Setup: Before testing the functions in apip/bin the environment variable LD_LIBRARY_PATH must include the full path name to apip/lib to enable dynamic linking to the libraries there. This does not work on HP workstations. It is also useful to add apip/bin to your PATH. It is recommended, but not required for the two environment variables be created for APIP. ITMP: Provides the path where images created by the utilities are stored. The routines search this directory first and then search the local directory. It is strongly recommended that this environment variable be defined. The utilites can quickly create a huge number of results that can lead to disc storage problems. The .logout file can be set to clear this working directory. Permanent storage of images is best done in subdirectories of this working directory. For example: mkdir ~/itmp setenv ITMP ~/itmp mkdir ~/itmp/astro APFORMAT: Defines the default image file format, choices are FITS and HDR. The default for the programs is FITS, so this is not essential for those wishing to use FITS as the default. setenv APFORMAT FITS [HDR] MANPATH: MANPATH has to be modified to gain access to the Man pages for APIP. Example of what .cshrc might contain: setenv APIP $HOME/ip/apip1.5 set path = ( $path $APIP/bin ) setenv ITMP $HOME/itmp/ ## The following is not necessary if FITS is the desired default ## setenv APFORMAT HDR setenv MANPATH /usr/man:/usr/local/man:/home/export/newsprint/man:/usr/lang/man:$APIP/doc ----------------------------------------------------------------- Directories: /apip Base directory which contains the following: /apip/include apImage.h apHeader.h apBasisProto.h apFitsProto.h apProto.h /apip/subs Subroutines for apUtils. /apip/mains Drivers for the subroutines. /apip/cluster Clustering drivers. /apip/cluster/subs Subroutines for clustering utilities. /apip/wavelets General 2D Wavelet Utility (Based on code from V. Wickerhauser). /apip/ps Postscript conversion utility. /apip/display (/apip/pcDisplay for Borland and MS VC) show showa flip /apip/scripts lsap lim rmimg clritmp /apip/bin Location for compiled functions. /apip/fits Subroutines for reading and writing FITS files. Original code supplied by Rick Ebert, IPAC. Code was modified to be ANSI compatible by CHA. /apip/tiff TIFF image file support. Unmodified code from Sam Leffler and Silicon Graphics. Version taken from the CDROM supplied with, "Encyclopedia of Graphics File Formats" James D. Murray and William vanRyper, O'Reilly \& Associates, ISBN 0-937175-058-9 This is a highly recommended source for general information about image file formats and code for conversions. /apip/steerpyr This contains code for steerable pyramids as provided by Eero Simoncelli. Two routines to interface his code to APIP are provided as experimental code. Makefiles are only given for the SUN operating system. ----------------------------------------------------------------- Basic Function Usage: Typing the name of a function with no arguments will result in a brief apUSAGE: statement. Generally this provides enough hints that you can try the operation. To start with one might try using the operator initi to create a small test image. Then apply prti and stati to query this test image. initi a 256 256 r f /* Creates image `a' 256 by 256 filled with random float values */ prti a /* prints out some values in the upper left corner of `a' */ stati a /* Simple statistics of a */ The format of the arguments does not follow standard UNIX operator parameter conventions. File redirection is NOT supported! Typical function form is: operator inputImage outputImage parameters [optional parameters] For example: Assume A B C are existing image files and X Y Z will be output names. lp3 apUSAGE: lp3 Input Output [shiftRight=0] lp3 A X { The input image A is lowpass filtered using a 3tap filter kernel and the result stored in X.} lp3 A X 1 { The shiftRight operation divides the result by 2^1 before storing the result in X. Negative values for shiftRight multiply the output values by 2^#. Not all negative values are supported in finite precision images.} lp3 Y Z apERROR: lp3 cannot load Y Errors will result in apERROR: messages. Some will be informative, as in this case where the operator cannot find the input image Y. Other error messages can reflect lack of memory resources, such as apERROR: lp3 could not allocate the output image. Unusually cryptic error messages like these are indicative of a programming error and should be reported to cha@shifter.wustl.edu. The file extensions of .fits or .img need not be appended to calls to the functions. When there are ambiguities the full file name is appropriate. Single files in an image array can be designated by appending the index number of the image to the end of the name. Thus to add the second to the fourth image of the array A addi A.1 A.3 Z The first image would be A.0. ----------------------------------------------------------------- Image file formats and data types supported: General limits to image files are: Max width and height = 4096 Max depth, or bands = 256 {These can be changed in apImage.h} All fits data types are supported, although some functions do not handle unsigned char when it is not appropriate. Most functions also work on other data types not supported by FITS, such as unsigned 16 bit ints and unsigned 32 bit ints. All operators handle blanks in float and double images, and for most of the other data types. The notable exceptions are the ALU functions, such as addi, which only handled floats and double. All operators work on image arrays subject to the limit of 256 bands. Data types supported by most, but not all, operators INT8 char UINT8 unsigned char INT16 short UINT16 unsigned short INT32 int UINT32 unsigned int (Support for this data type is being removed.) FLOAT float DOUBLE double Complex numbers are not supported, but in the fft utilities they are treated as an image array of depth 2. ----------------------------------------------------------------- Function List: Name: Operation: Basic utilities: ascii2i Convert ascii file to image file. cpi Copy image files, change formats. initi Create images for tests. prthdr Print image file header info. prti Print limited set of values. statnh Simple statistics (no histogram). stati Stats with histogram. toBytes Convert to unsigned 8 bits. toTiff Convert to unsigned 8 bit TIFF. tiff2i Convert Tiff to FITS or HDR images. toPs Generate a Postscript File. Display: flip Flip through an array. show Show a single image. showa Displays an array of images. Unary operations: absi Absolute Value. boundi Clip to max and min values. corei Remove small amplitude noise. filli Fill image with constant. noti Logical NOT values. onOff Outputs (on>=threshold), (off<=threshold). scalei Rescale and add a constant. sqri Square the values. sqrti Square Root values. logi Log base e. swapBytes Does this to image data. Binary ALU operations: addi Add 2 images. divi Divide 2 images. multi Multiply 2 images. maxi Max of 2 images. subi Subtract 2 images. Filter operations: blkave Filter with rectangular block. filteri General filter routine. lp Lowpass filter. bp Bandpass filter. filx Linear filter along horizontal axis. fily Vertical linear filter. Reduce operations: (Lowpass filter followed by down sampling by 2) reducei Expand operations: (Up sample by 2 followed by a lowpass filter) expandi Gaussian Pyramids: (Recursive reduce operation) gauss zgauss (1D Gaussian pyramid along depth axis.) Laplacian Pyramids: (Recursive bandpass filters) lap FSD Laplacian Pyramid. burt Burt Laplacian Pyramid. burtDbl Double Density Pyramid. burt3d 3D Burt Pyramid. zburt 1D Burt Pyramid along depth axis. Inverse Laplacian Pyramid Transforms: recLap FSD Laplacian Pyramid recBurt Burt Laplacian Pyramid Oriented Pyramids: ori Create oriented pyramid. recOri Reconstruct. oripower oriented power orimap contrast independent orientations. Gradient Pyramids: gradpyr Gradient pyramid. gradlpyr Laplacian gradient. recGrad Reconstruct gradient. recGradL Reconstruct Laplacian gradient. Wavelet: wavelet General wavelet utility. Beylkin,Coifman,Daubechies,Vaidyanathan FFT: fft Fast Fourier Transform ffti Inverse FFT fftp Complex Power Blank Utililites: setBlanks Sets pixels of a given value to blanks. zeroBlanks Converts blanks to 0. createmask Generates a mask from an image. Insert-Extract: extracta Extract a subarray in depth. extracti Extract a subimage. inserti Insert a subimage. Cluster: clusti Creates linked clusters. statc Print cluster statistics. prtc Print coordinates of clusters. Misc: autogain Normalizes Laplacian Contrast. cloud Generates cloud like images. contrast Local contrast of Laplacian bands. enhance Zoom up, generate new high spatial freq. intermit Intermittency measures. xscalecorr Cross Scale Correlations. --------------------------------------------------------------- Standard kernels used in the filter operators. 3 Tap: Separable Filter H[x][y] = h[x]*h[y]; h[x] = {1/4,1/2,1/4} 5 Tap: Separable Filter H[x][y] = h[x]*h[y]; h[x] = {1/16,1/4,3/8,1/4,1/16} 7 Tap: H[x][y] = { 0, 5, 13, 16, 13, 5, 0, 5, 25, 52, 64, 52, 25, 5, 13, 52, 102, 126, 102, 52, 13, 16, 64, 126, 156, 126, 64, 16, 13, 52, 102, 126, 102, 52, 13, 5, 25, 52, 64, 52, 25, 5, 0, 5, 13, 16, 13, 5, 0 } /4096; --------------------------------------------------------------- apHDR File format: This primitive image file format allows general access to many image files if the width,height,data type and offset to the raw image data are known. History: Source Code Author: Jerry E. Solomon 11/21/88 Copyright and Right to License Belong to: California Institute of Technology Pasadena, CA 91125 Revised 5/90 by Susan Eberlein to support various image formats and to support image names ending only in .img Extensively revised by C. H. Anderson --------------------------------------------------------------- Image data and header information exists in separate files. Image data is in the file `Image' or `Image.img' The .img extension is optional. When the .img extension does not exist, appending it to a file name will disambiguate it from .fits files of the same base name. The Image Header file `Image.hdr' contains a list of ascii keywords in the form keyword = value keywords can be in any order, but limited to one per line. Required keywords are: width {or samples} = # height {or lines } = # type = (data type as an ascii string, unsigned int, float etc.) There is one optional keyword that does not require the `='. This indicates how multiband spectral data is organized. Values for this keyword {and optional variants} are: FRAME {frame,AOTF,aotf} /* Frame sequential */ ROW {row, CIPE,cipe} /* Row sequential */ PIXEL {pixel,AES, aes} /* Pixel sequential */ [NOTE: The FITS file implementation only supports the type FRAME] Optional keywords: bands {or depth} = # (Number of frames, or spectral bands). offset = # (Offset in bytes to raw data in the data file) blank = # (Value for blank values in the image, can be set to 1 for floats and doubles, in which case it is used as a truth value.) User keywords are supported.