1.. $URL$ 2.. $Rev$ 3 4Why Use PyPNG? 5============== 6 7In order to motivate you into using PyPNG this document discusses some 8of the reasons for using PyPNG over other software. 9 10For starters I assume you already love PNG. If you don't want to read 11and write PNG files then you don't want to use PyPNG. 12 13The most obvious "competitor" to PyPNG is PIL. Depending on what job 14you want to do you might also want to use Netpbm (PyPNG can convert to 15and from the Netpbm PNM format), or use ``ctypes`` to interface directly to a 16compiled version of libpng. If you know of others, let me know. 17 18PyPNG is written in Python. Python is clearly the coolest sexiest 19language going, so PyPNG is cool and sexy too. By association. 20 21Because PyPNG is written in Python it's trivial to install into a Python 22installation, or include in your application (as long as it's written in 23Python!). Just use ``python setup.py install`` or just copy the 24``code/png.py`` file. You can even `curl` it straight into wherever you 25need it: ``curl -O http://pypng.googlecode.com/svn/trunk/code/png.py``. 26In fact, I have never managed to install PIL and that was one of the 27motivating factors for PyPNG. So PyPNG will always be easy to install. 28 29PyPNG can read and write all PNG formats. PNG supports a generous 30variety of image formats: RGB or greyscale, with or without an alpha 31channel; and a choice of bit depths from 1,2, or 4 (as long as you want 32greyscale or a pallete), 8, and 16 (but 16 bits is not allowed for 33palettes). A pixel can vary in size from 1 to 64 bits: 341/2/4/8/16/24/32/48/64. In addition a PNG file can be `interlaced` or 35not. An interlaced file allows an incrementally refined display of 36images being downloaded over slow links. 37 38PIL, according to its handbook, does not support interlaced PNG 39files. Also, PIL only has internal representations (PIL `mode`) 40for 1-bit and 8-bit channel values. This makes me wonder if PIL 41can read PNG files with bit depth 2 or 4 (greyscale or palette), 42and also bit depth 16 (which PNG supports for greyscale and RGB 43images). In addition, PIL has only "limited support" for greyscale 44with alpha, which is one of PNG's supported formats (in 8 and 16 45bits per channel). 46 47I don't mean to belittle PIL here, PIL's focus is not PNG. PIL's focus 48is image processing, and this is where PyPNG sucks. If you want to 49actually process an image---resize, rotate, composite, crop--then you 50should use PIL. This is simply out of scope for PyPNG. In PyPNG you 51get the image as basically an array of numbers. So some image 52processing is possible fairly easily, for example cropping to integer 53coordinates, or gamma conversion, but in any case PyPNG provides no 54support for it. In the future a sister project to PyPNG may add some 55simple image processing, but processing in pure Python will be way slow. 56 57PyPNG (when used in its command-line mode) can read and write Netpbm 58PAM files. PAM is useful as an intermediary format for performing 59processing; it allows the pixel data to be transferred in a simple format 60that is easily processed. A typical workflow using PAM might be: 61 62PNG to PAM ... process PAM file (for example, resize) ... PAM to PNG 63 64Using PAM as an intermediate format is preferred over having to 65carry around your alpha channel in a separate file; it allows 66workflows to be pipelined more easily. 67 68When reading PAM files a single source file can be used to create 69PNG files with all permitted channel combinations: greyscale, 70greyscale--alpha, RGB, RGBA. When writing a PAM file is created for 71those PNG formats with an alpha channel, otherwise a compatible PGM or 72PPM file is created. 73 74Netpbm's support for PAM to PNG conversion is more limited than PyPNG's. 75Netpbm will only convert a source PAM that has 4 channels (for example it does 76not create greyscale--alpha PNG files from ``GRAYSCALE_ALPHA`` PAM files). 77Netpbm's usual tool for create PNG files, ``pnmtopng``, requires an alpha 78channel to be specified in a separate file. 79 80PyPNG has good support for PNG's ``sBIT`` chunk. This allows end to end 81processing of files with any bit depth from 1 to 16 (for example a 8210-bit scanner may use the ``sBIT`` chunk to declare that the samples in 83a 16-bit PNG file are rescaled 10-bit samples; in this case, PyPNG 84delivers 10-bit samples). Netpbm handle's the ``sBIT`` chunk in a 85similar way, but other toolsets may not (PIL?). 86 87``libpng`` is made by the PNG gods, so if want to get at all that 88goodness, then you may want to interface directly to libpng via 89``ctypes``. That could be a good idea for some things. Installation 90would be trickier. 91