------------------------------------------------------------------------------- IMG* Image Processing Toolset and C Library Version 1.1 (Nov 1994) Copyright 1994 Simon A.J. Winder sajw@maths.bath.ac.uk All Rights Reserved ------------------------------------------------------------------------------- Contents -------- 1. Installation 2. Contents of this Directory 3. Introduction 4. List of Image Processing Tools 5. ImgStar C Library 6. File Formats 7. Known Bugs 8. Update History ------------------------------------------------------------------------------- 1.Installation -------------- After down-loading the package and unpacking, type "make" in this directory to build the C library in LibSrc and the image processing toolset in ToolsSrc. Problems that may require attention: 1. You may need to use a different compiler than gcc. If this is the case then change the CC line in the top level Makefile. You may also have to change the compile flags by editing the CFLAGS line. 2. All the code uses ANSI declarations, so you need to use a compiler that can handle this or you will immediately get a lot of compile errors. 3. The tool named imgSurfacePlot is linked with the X11 libraries for the Athena Widget set. Check your local X configuration to find out which X library files are necessary and in what order they must be linked. Edit the XAW line in ToolsSrc/Makefile to change this. 4. If you have trouble compiling imgCrop then it may be that your preprocessor does not understand the ## directive, so edit the CAT macro in ToosSrc/tools.h to be #define CAT(a,b) a/**/b instead of #define CAT(a,b) a##b This will fix the problem providing your preprocessor leaves no space when replacing /**/. ------------------------------------------------------------------------------- 2. Contents of this Directory ----------------------------- Makefile Makefile to build the package copyright.txt Copyright notice introduction.txt This introduction file lib_manual.txt Documentation for the image processing C library tools_manual.ps Postscript image processing tools manual (80 pages) example.c Example program to introduce the C library venice.pgm A monochrome image to test the tools with Bin Directory in which the binaries are placed LibSrc Source code for the C library ToolsSrc Source code for all 70 tools ------------------------------------------------------------------------------- 3. Introduction --------------- The ImgStar Image Processing Tools are intended as a complete environment for image processing to compliment Jef Poskanzer's pbmplus toolkit which mostly provides conversion between different standard file formats. All 70 ImgStar tools use a similar UNIX command line invocation style which includes a self documenting "-h" option. Images are piped between operators, each of which provides some filtering transformation. A floating point image format is introduced in order to allow image processing operations to be cascaded usefully. Conversion tools are included to convert between this and the PBM-type formats. Both binary and ASCII floating point formats are supported so that image data can be edited and transferred between hosts having different architectures. Tools are included that implement arithmetic and logical operations; magnify, crop and subsample; implement edge detection (e.g. Canny); allow custom space-domain or frequency-domain convolution; include high-pass, low-pass, band-pass, rank-value, difference-of-Gaussians and Gabor filtering; generate test images and implement differential or vector operations e.g. gradient, derivatives, Laplacian. There are also a variety of miscellaneous tools e.g. thresholding, zero-crossing detection, and calculation of image statistics. For example, the following implements Canny's edge detection scheme: imgPnmToFlt <venice.pgm |imgSmooth 2 |imgCanny |imgEdgeSynth 1 3 |xv - In addition to the processing of single images, all the ImgStar tools include support for sequential processing of multiple images from a single command line. This is useful when similar operations need to be applied to many images such as when motion sequences are being analysed. A comprehensive set of sequence handling tools allow many useful processing schemes to be set up with a minimum of commands. An 80-page postscript manual describes each tool and provides a short introduction with examples. In addition, documentation is included for the C library which is used by the toolset to handle images and to carry out common operations. This library supports various kinds of fast colourmap and histogramming operations and includes easy-to-use functions for creating and destroying, loading, saving and manipulating image data. Users are encouraged to write their own operators in C, using one of the ImgStar tools' source code as a template. A complete and compact image processing environment would include the ImgStar tools and C library, the pbmplus toolkit, John Bradley's XV image viewing program and maybe David Koblas' XPAINT to create test images. The ImgStar package requires only about 3.5Mbytes of disk space which also makes it a useful complement to any existing image processing environment. ------------------------------------------------------------------------------- 4. List of Image Processing Tools --------------------------------- Bit image (pbm) manipulation tools: imgAnd imgNot imgOr imgXor Arithmetic operations: imgAbs imgAdd imgDiv imgMul imgMax imgNeg imgPower imgRectify imgSub imgWrapAngle Tools that change image sizes: imgCrop imgMagnify imgSubSample Tools that generate images: imgGrating imgImage imgImpulse Tools that display information about an image: (xv) imgInfo imgPrint imgStats imgSurfacePlot Tools that implement space domain transformations: imgConvolve imgFoveate imgNoise imgRankFilter imgSmooth Tools that are involved in edge detection: imgCanny imgEdgeSynth(2) imgMarrHil imgThresh imgZeros Tools that allow Fourier domain filtering: imgForwardFFT imgFourierPad imgInverseFFT imgCpxMul imgFFTBandPass imgFFTDOG imgFFTGabor imgFFTHigh imgFFTLow imgFFTSmooth Tools that convert between image types: imgAscii imgCpxToFlt2 imgFlt2ToCpx imgFlt3ToPpm imgFltToPgm imgFlip imgPnmToFlt imgPpmToColour imgPpmToFlt3 imgReorder imgSetMinMax Derivatives and vector operators: imgAngle imgDeriv imgGrad imgLaplacian imgMagnitude Tools that handle image sequences: imgCombine imgCombineSeq imgInsert imgRepeat imgSelect imgSplit imgSplitSeq imgTee ------------------------------------------------------------------------------- 5. ImgStar C Library -------------------- Documentation for the C library is included in lib_manual.txt. This file contains information about the general purpose image structure and support routines. Source code for the library is found in LibSrc and the image.h header file and libimg.a archived library file also reside there. Included in this directory is an example program which makes a reverse-video version of a pgm file that is passed to it via stdin. This program is compiled using the line: gcc example.c -o example -ILibSrc -LLibSrc -limg or gcc example.c -o example LibSrc/libimg.a -ILibSrc If you have XV and a suitable pgm (monochrome) image then you can test the program with: example <venice.pgm | xv - This will process the image and view the results using XV. ------------------------------------------------------------------------------- 6. File Formats --------------- The C library and tools support loading and saving of 16 file formats. There are eight different types and each can be written in ASCII or binary mode. The ASCII versions can be usefully edited. The types are as follows: Magic Number --- Pbmplus Image Formats ----------------- ASCII ------ Binary ------ Black and white bit images (.pbm files). P1 P4 Grey level images (.pgm files). P2 P5 24-bit colour images (.ppm files). P3 P6 --- IMG* Image Formats -------------------- ASCII ------ Binary ------ Long word images (32 bit). ILibLong ILibRawLong Float images (.flt files). ILibFloat ILibRawFloat Double precision floating point images. ILibDouble ILibRawDouble Complex images (.cpx files). ILibComplex ILibRawComplex Polar images. ILibPolar ILibRawPolar The polar format is not often used and is included for historical reasons. For pbmplus formats please see the documentation with the pbmplus package. IMG* files have a standard header containing information about the type of image, the dimensions, the region of the image to treat as valid for future operations and the minimum and maximum pixel values. These may be interspersed with comment lines prefixed by a #. The arrangement is as follows: MagicNumber width height valid_x valid_y valid_width valid_height min_value max_value image_data The image data is either an ASCII or a binary pixel dump, which may be followed but not preceded by arbitrary white space. In the case of ASCII data, there should not be more than 70 characters on each line. ------------------------------------------------------------------------------- 7. Known Bugs ------------- 1. The arithmetic image tools should calculate min and max values over the valid region, not the whole image. Use imgSetMinMax to overcome this. 2. The image library should include support for N-dimensional floating point pixel data, rather than just 1 (IT_FLOAT) or 2 (IT_COMPLEX) dimensions. This is partially overcome by using multiple floating point files and by using the sequence processing capabilities. ------------------------------------------------------------------------------- 8. Update History ----------------- V1.0 Oct 1994: V1.1 Nov 1994: 1. imgNCanny withdrawn. 2. imgMarrHil now produces same output type as imgCanny and "number" parameter has been removed. 3. imgEdgeSynth and imgEdgeSynth2 swapped over. 4. -Wall flag removed from makefiles. 5. Compilation includes library file directly rather than via -L flag. 6. Typos in manual corrected. 7. Documentation updated. 8. All dependencies on preprocessor string concatenation removed to allow for more compiler types. 9. Removed occurences of =-, =*, =& which generate lots of warnings with some compilers. 10. Added manual page documentation for imgMax and imgFlip. 11. Added self documentation by -h flag to all tools. 12. imgFFTDOG now has rc and rs specified in the same way as imgGaussian. ------------------------------------------------------------------------------- Simon A.J. Winder Wed Nov 23 21:17:24 GMT 1994 -------------------------------------------------------------------------------