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