
Supplemental notes on using the libraries
31 May 03
==========================================

First, read the README to get an overview of what is available
and how to use it.

This supplements that information in particular areas.

1.  I/O  (ref: section 12 of the README)

    When building programs, it is often important to look at images.
    The function
        pixWrite(char *filename, PIX *pix, INT32  format)
    writes an image to file.  See any of the programs in the prog
    directory for examples.

    You can display this image with a variety of programs, such as
    xv (which scales the image automatically to fit on the screen)
    display (which displays at full resolution), gqview (which displays
    at full resolution and allows easy zooming), and gimp (which is
    set up for image manipulation and displays by default at low
    resolution).   For programmatic display with xv, we provide a function
        pixDisplay(PIX  *pix, INT32 x, INT32 y)
    which scales the image to fit on the screen if necessary and
    then displays it with the UL corner at (x, y).

    Images are read into memory from file using
        PIX   *pixRead(char *filename)
    For the file formats that are supported (BMP, PNG and JFIF_JPEG),
    the extension (if any) is ignored and the format type is determined
    from the file itself.

2.  The PIX data structure

    The PIX data structure is the internal (memory) representation
    of images in this library.  It is very simple, and is
    described in pix.h, along with some of the flags and other
    data structures that are associated with it.  The field accessors
    for PIX, provided in pix1.c, should ALWAYS be used. 
    The pixClone() function is used to get a new handle (pointer)
    to the same PIX data structure, without actually copying the image
    data to a new array.  The pixDestroy(PIX **) function should be
    used on every handle you have -- see the comments in pix1.c
    at the pixClone() definition.


