
The Python Imaging Library
$Id: README$

Release 1.0 beta 1 (January 1, 1999)

====================================================================
The Python Imaging Library 1.0 beta 1
====================================================================

Contents
--------

+ Introduction
+ Software License
+ Build instructions for UNIX
+ Build instructions for Windows

--------------------------------------------------------------------
Introduction
--------------------------------------------------------------------

The Python Imaging Library adds image processing capabilities to your
Python interpreter.  This library provides extensive file format
support, an efficient internal representation, and fairly powerful
image processing capabilities.

This is hopefully the only beta release of 1.0 (formerly known as
0.3).  If no serious problems are found with this release, it will
be rereleased as 1.0 final before then end of January 1999.

This source kit has been built on Windows 95, 98 and NT, as well as
on Linux (Redhat 4.2) and Digital Unix.  It should build out of the
box on most mainstream Unix versions.

The main distribution site for this software is:

	http://www.pythonware.com

The PIL handbook is not included in this distribution; to get the
latest version (which may not be entirely up to date at the time of
this release), check:

	http://www.pythonware.com/library.htm

--------------------------------------------------------------------
News highlights in 1.0b1 (as compared to 0.2):

+ Improved font support.  The pilfont package is now included
  in the core distribution.

+ Improved graphics support, including arc, chord, and pieslice
  primitives.

+ Conversion to "P" and "1" uses Floyd-Steinberg dithering.
  Conversion to "P" can use "web" colours or adaptive palette.

+ Added support for "YCbCr" image memories.

+ Added support for 32-bit integer and floating point images,
  including new decoders to deal with many kinds of input data.

+ The Tk interface now supports transparent images.
  *** NOTE: the Tk interface has been changed; you need to update
  *** your Tkinter build to properly handle the new interface.

+ Added read support for IPTC/NAA Newsphoto, McIdas, PIXAR raster,
  FlashPix, Microsoft Image Composer, and XV thumbnails.

+ Lots and lots of bug fixes.

For more information on these and other changes, see the CHANGES
document.

For installation and licensing details, see below.

For questions, comments and bug reports, send mail to
'image-sig@python.org'.

--------------------------------------------------------------------
Software License
--------------------------------------------------------------------

The Python Imaging Library is

Copyright (c) 1997-1999 by Secret Labs AB
Copyright (c) 1995-1999 by Fredrik Lundh

By obtaining, using, and/or copying this software and/or its
associated documentation, you agree that you have read, understood,
and will comply with the following terms and conditions:

Permission to use, copy, modify, and distribute this software and its
associated documentation for any purpose and without fee is hereby
granted, provided that the above copyright notice appears in all
copies, and that both that copyright notice and this permission notice
appear in supporting documentation, and that the name of Secret Labs
AB or the author not be used in advertising or publicity pertaining to
distribution of the software without specific, written prior
permission.

SECRET LABS AB AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO
THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS.  IN NO EVENT SHALL SECRET LABS AB OR THE AUTHOR BE LIABLE FOR
ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.


--------------------------------------------------------------------
Build instructions for UNIX
--------------------------------------------------------------------

NOTE: To build the Python Imaging Library, you need an ANSI C com-
piler.  The "cc" compiler on SunOS 4 is *not* ANSI compliant.  On that
platform, use "acc" or "gcc" instead.  On some platforms, you may have
to use compiler options like "-ansi" or "-std" to get full ANSI C
support.

1. If you need JPEG and/or PNG support, make sure to get and build
   the necessary external libraries:

   - for JPEG support, get the IJG JPEG library, version 6a or 6b.

   - for PNG and ZIP support, get the ZLIB library (by Gailly/Adler).
     PIL was tested with version 1.0.4, but is likely to work with
     versions from 0.95 and onwards.

     If you have RedHat 4.2 or newer, the libraries provided with
     the operating system should work just fine.


2. Unpack the PIL distribution (the file Imaging-1.0b1.tar.gz) in your
   Python/Extensions directory.

	$ cd Python-1.5/Extensions # example
	$ gunzip Imaging-1.0b1.tar.gz
	$ tar xvf Imaging-1.0b1.tar


3. Now build the Imaging core library (libImaging.a):

	$ cd Imaging-1.0b1/libImaging
	$ ./configure
	$ make

   If you need to specify additional compiler options, the
   second line should look something like:

	$ CC="cc -ansi" ./configure


4. To check that this library works as it should, type:

	$ make check

   (It isn't much of a test, but at least it shouldn't crash :-)


5. Go back to the Imaging directory.

   If you don't have the IJG JPEG or ZLIB libraries (or you have them,
   but not in a standard place), copy the "Setup.in" file to "Setup"
   and edit it according to the instructions in the file.


6. Edit Makefile.pre.in and build a Makefile following the instructions
   there.  In most cases, you can simply give the following command:

	$ make -f Makefile.pre.in boot


7. To build a dynamically loaded module, just type "make":

	$ make

   This will create a file called "_imaging.so".

   Then type (assuming a standard shell):

	$ PYTHONPATH=.:./PIL ; export PYTHONPATH
	$ python

	>>> import _imaging
	>>> import Image

   If both imports works, you've successfully added PIL to your Python
   environment.  There are a few demo scripts in the Imaging/Scripts
   directory that you can use to further test the library.


8. Copy the "_imaging.so" module and the contents of the "Imaging/PIL"
   directory to a suitable place along the Python path.

   If you're using Python 1.5 or later, the preferred way is to create
   a "PIL" subdirectory under "site-packages", copy the "PIL.pth" file
   to "site-packages", and the rest of the files to the new subdirectory.

   Example:

	$ cp PIL.pth /usr/local/lib/Python1.5/site-packages
	$ mkdir /usr/local/lib/Python1.5/site-packages/PIL
	$ cp _imaging.so PIL/* /usr/local/lib/Python1.5/site-packages/PIL


* Adding Tkinter support

1. Compile Python's _tkinter.c with the WITH_APPINIT and WITH_PIL
   flags set, and link it with tkImaging.c and tkappinit.c.  To
   do this, copy the former to the Modules directory, and edit
   the _tkinter line in Setup (or Setup.in) according to the
   instructions in that file.

   NOTE: if you have an old Python version, the tkappinit.c
   file is not included by default.  If this is the case, you
   will have to add the following lines to tkappinit.c, after
   the MOREBUTTONS stuff:

	{
	    extern void TkImaging_Init(Tcl_Interp* interp);
	    TkImaging_Init(interp);
	}

   This registers a Tcl command called "PyImagingPhoto", which is
   use to communicate between PIL and Tk's PhotoImage handler.

   You must also change the _tkinter line in Setup (or Setup.in)
   to something like:

   _tkinter _tkinter.c tkImaging.c tkappinit.c -DWITH_APPINIT
	-I/usr/local/include -L/usr/local/lib -ltk4.2 -ltcl7.6 -lX11


--------------------------------------------------------------------
Build instructions for Windows
--------------------------------------------------------------------

The current release does not include Windows makefiles.  You can get
a prebuilt version from:

	http://www.pythonware.com/downloads.htm

That version is compatible with Python interpreters build using
Microsoft Visual C++ 5.0.

Building your own copy under Visual Studio should be straightforward;
create a new project based on the sample extensions provided with
Python (the target should be "_imaging.dll"), add all C files except
"Except.c" and "coretest.c" to that project, check the contents of the
"ImConfig.h" file (modify it if necessary), and build the DLL.

(If I'd used Visual Studio myself, I would have provided a project
file.  But I don't.  Contributions are welcome, though...)

--------------------------------------------------------------------
NOTE: If you use Tk on Windows, you may wish to install the booster
patches which provides dramatic performance improvements for 16- and
24-bit displays.  See the description in the Tk subdirectory for
details.
--------------------------------------------------------------------
