### ImgStar-0.1 README file

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

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