
The Python Imaging Library
$Id: //modules/pil/README#22 $

Release 1.1.4 (May 10, 2003)

====================================================================
The Python Imaging Library 1.1.4
====================================================================

Contents
--------

+ Introduction
+ Support Options
  - Commercial support
  - Free support
+ News Highlights
+ Software License
+ Build instructions for UNIX
  - Additional notes for Sun Solaris
+ Build instructions for Mac OS X
+ Build instructions for Windows

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

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

This source kit has been built and tested on Windows NT/2000/XP,
Mac OS X, and a number of Unix platforms (including Alpha, Solaris
and Intel systems).  We believe that it should work on most modern
platforms (people are using it on Crays, after all ;-)

The main distribution site for this software is:

        http://www.pythonware.com/products/pil/

That site also contains information about free and commercial support
options, PIL add-ons, answers to frequently asked questions, and more.


Development versions (alphas, betas) are available here:

        http://effbot.org/downloads/


The PIL handbook is not included in this distribution; to get the
latest version, check:

        http://www.pythonware.com/library/
        http://effbot.org/books/imagingbook/ (drafts)


For installation and licensing details, see below.


--------------------------------------------------------------------
Support Options
--------------------------------------------------------------------

+ Commercial Support

Secret Labs (PythonWare) offers support contracts for companies using
the Python Imaging Library in commercial applications, and in mission-
critical environments.  The support contract includes technical support,
bug fixes, extensions to the PIL library, sample applications, and more.

For the full story, check:

        http://www.pythonware.com/products/pil/support.htm

Or send a mail to:

        sales@pythonware.com

You can also buy support tickets which cover one support indicent,
with up to one hour of engineering time.  For more information, see:

        http://www.pythonware.com/support


+ Free Support

For support and general questions on the Python Imaging Library, send
e-mail to the Image SIG mailing list:

        image-sig@python.org

You can join the Image SIG by sending a mail to:

        image-sig-request@python.org

Put "subscribe" in the message body to automatically subscribe to the
list, or "help" to get additional information.  Alternatively, you can
send your questions to the Python mailing list, python-list@python.org,
or post them to the newsgroup comp.lang.python.


--------------------------------------------------------------------
News Highlights in 1.1.4 (as compared to 1.0):
--------------------------------------------------------------------

+ Adapted to Python 1.6, 2.0, 2.1, 2.2 and 2.3b1.  This version
  also runs under 1.5.2, but probably not under versions older
  than that.

+ To reduce module dependencies, the Tkinter support has been
  moved to a separate binary module.

+ The JPEG decoder is more tolerant for broken files.  As long
  as all image data can be read, it won't complain.

+ An ANTIALIAS downsampling filter has been added.

+ TrueType/OpenType support has been added (based on the
  freetype 2.0 library).

+ Now supports Screen grabbing and clipboard copy on Windows.

+ Includes distutils build script (setup.py) for 2.0 and later.

+ The usual crop of bug fixes and performance tweaks.

For detailed information on these and other changes, see the CHANGES
documents.


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

The Python Imaging Library is

Copyright (c) 1997-2003 by Secret Labs AB
Copyright (c) 1995-2003 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.

     You can find this library here:

          http://www.ijg.org
          ftp://ftp.uu.net/graphics/jpeg/

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

     You can find this library here:

          http://www.info-zip.org/pub/infozip/zlib/

  - for TrueType/OpenType support, get the FreeType 2.0 library
    (by Turner et al) from:

          http://www.freetype.org
          http://freetype.sourceforge.net  

  - If you have a recent Linux version, such as RedHat 6, the
    libraries provided with the operating system should work just
    fine.

   If you're using Mac OS X, you can use the 'fink' tool to
   install these libraries (also see the Mac OS X section below).


2. If you didn't build Python from sources, make sure you have
   Python's build support files on your machine.  If you've down-
   loaded a prebuilt package (e.g. a Linux RPM), you probably
   need additional developer packages.

   If this doesn't mean anything to you, you can still carry out
   steps 3 to 5 as described below.  Step 6 will probably fail,
   though.


3. Unpack the PIL distribution (the file Imaging-1.1.4.tar.gz)
   in your Python extensions directory (if you have one.  If
   not, feel free to unpack it in any other suitable directory).

        $ cd Python-2.2/Extensions # example
        $ gunzip Imaging-1.1.4.tar.gz
        $ tar xvf Imaging-1.1.4.tar


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

        $ cd Imaging-1.1.4/libImaging
        $ ./configure
        $ make

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

        $ CC="cc -ansi" ./configure


5. When the build has finished, go back to the Imaging directory.

        $ cd ..


6. If you're using Python 2.0 or later, you can use the setup.py
   script to finish the build.  The following commands should do
   the trick:

        $ python setup.py build
        $ python setup.py install

   (depending on how Python has been installed on your machine,
   you might have to log in as a superuser to run the 'install'
   command.)

   If the setup.py command finishes without any errors, you're
   done!

   If you have an older Python version, or if the setup.py script
   cannot figure out how your system is configured, you can build
   PIL in the traditional way, using the Setup.in file.  See steps
   7 through 10 below for details.


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


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

   If this doesn't generate a Makefile, you probably don't have the
   necessary build files on your machine.  See step 2 above for more
   information.


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

        $ make

   This will create two files; "_imaging.so", and "_imagingtk.so"
   (the latter isn't created if you commented out the Tcl/Tk inter-
   face section in Setup.in)

   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.

   To to a slightly more extensive test, you can run the selftest
   regression test suite:

        $ python selftest.py

   There are a few demo scripts in the Scripts directory that you
   can use to further test the library.


10. Copy the "_imaging.so" module, the "_imagingtk.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 *.so PIL/* /usr/local/lib/Python1.5/site-packages/PIL

   You can also place "PIL" subdirectory anywhere along the Python
   path, and use PIL as a package.

   Example:

        $ mkdir /usr/local/lib/Python1.5/PIL
        $ cp *.so PIL/* /usr/local/lib/Python1.5/PIL


--------------------------------------------------------------------
Additional notes for Sun Solaris
--------------------------------------------------------------------

On some Solaris installs, you may get errors like "text relocation
remains against symbol" and "ld: fatal: relocations remain against
allocatable but non-writable sections" when building PIL.

To work around this problem, you need to compile the libImaging
library with the -fPIC flag.  Replace the configure call in step 4
above with

	$ CFLAGS="-fPIC" ./configure

Alteratively, you can add -fPIC to the CFLAGS line in the Makefile
AFTER running configure but BEFORE issuing the make command.


--------------------------------------------------------------------
Build instructions for Mac OS X
--------------------------------------------------------------------

To build PIL on Mac OS X, see "Build instructions for UNIX".

On Mac OS X you will usually install additional software such as
libjpeg or freetype with 'fink', and then it ends up in /sw.

If that is your setup too, you should replace the configure call
in step 4 with

	$ LDFLAGS="-L/sw/lib" CPPFLAGS="-I/sw/lib" ./configure
	
and then edit libImaging/Makefile to correct the definition of
JPEGINCLUDE:

	JPEGINCLUDE=/sw/include


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

If you're using Python 2.0 or later, you can use the setup.py script
to build the library.  The following commands should do the trick:

        $ python setup.py build
        $ python setup.py install

You may need to tweak the setup.py file somewhat in order to make it
find certain external libraries; see comments in the file for details.


Note that most Python distributions include libraries compiled for
Microsoft Visual Studio.  To build extensions using other tool chains,
see the "Using non-Microsoft compilers on Windows" section in the
distutils handbook:

	http://www.python.org/doc/current/inst/non-ms-compilers.html

For additional information on how to build extensions using the
popular MinGW compiler, see:

	http://mingw.org (compiler)
	http://sebsauvage.net/python/mingw.html (build instructions)
	http://sourceforge.net/projects/gnuwin32 (prebuilt libraries)


If you cannot get the setup.py script to work, even after tweaking it
(see comments in the file), you can build the library by hand.  The
following approach should work with Visual Studio 5.0 and 6.0:

- create a new project based on the sample extensions provided with
  Python (the target should be "_imaging.pyd")

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

- build the DLL (PYD).

- copy the DLL (PYD) and the contents of the PIL directory to some
  suitable location on your Python path.

NOTE: Make sure to build PIL with the same linking options as was used
for the Python interpreter (usually /MD).  If you mix link options,
anything can happen...  (if you manage to link the library anyway, the
most common problem is that "save" doesn't work!)

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