-------------------------------------------------------------------------------


              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
-------------------------------------------------------------------------------