
################################################################################
this is a moderately sophisticated python3.0 script fully utilizing
extensions, & demonstrated to run under python2.6 via py3to2.
for performance, portions of it have been inlined w/ direct C code using
scipy.weave.  the algorithm also heavily uses bitwise operations.
it takes a jpg, gif... image file & outputs it in colorized ascii art.
also serves dual purpose as a 3-d colorized scientific plotter in text terminals
(screenshots of image conversion & 3d plot in putty terminal included)

if something fails, try updating ur install of py3to2 to the latest version @:
http://pypi.python.org/pypi/py3to2

how to enable 256 color on putty: http://www.emacswiki.org/emacs/PuTTY#toc2
how to enable 256 color on xterm: http://www.frexx.de/xterm-256-notes/

asciiporn is hard-coded to use lucida-console font, but courier looks ok.
the screenshot shows putty w/ lucida-console 5pt.

AUTHOR:
  kai zhu
  kaizhu@ugcs.caltech.edu

REQUIREMENTS:
- posix/unix os (Windows currently unsupported)
- py3to2
- Python Imaging Library
- scipy

PSEUDOMETHOD:
  asciiporn uses ".." syntax notation for pseudomethods
  goto: http://pypi.python.org/pypi/pseudomethod
  for more details about this feature

API:
  asciiporn module:
  - img2plaintxt - converts image file to portable plain txt
                   u can copy & paste in documents
  - img2txt - converts image to high-quality colorized txt
              for display on terminals supporting 256 color (putty, xterm...)
  - tplot3d - 3d color scientific plotter

INSTALL:
  python setup.py build
  python setup.py install
  python setup.py dev --quicktest

################################################################################
IMAGE USAGE:
  start up the py3to2 interpreter by typing "py3to2" in ur terminal &
  import asciiporn:
    $ py3to2

    Python 2.6.py3to2 (r26:66714, Nov 18 2008, 00:56:43)
    [GCC 3.4.6 20060404 (Red Hat 3.4.6-10)] on linux2
    Type "help", "copyright", "credits" or "license" for more information.
    >>>
    >>> import asciiporn
    created...
    py3k server starting...
    >>> ...py3k server started w/...
    >>>

  in this example, u'll b loading the image file included w/ this distribution,
  "mario.jpg".  its a fairly large image, so u probably want to scale it down
  to 0.5 (or less):
    >>> colortxt = asciiporn.img2txt("mario.jpg", scale = 0.5)
    >>> print( colortxt )

    ... beautiful image appears ^_-

    >>> plaintxt = asciiporn.img2plaintxt("mario.jpg", scale = 0.5)
    >>> print( plaintxt )

    ... rather plain b/w img -_-, but u can copy & paste in documents

  actually, the plaintxt prolly won't look well when pasted,
  b/c most document readers invert the color:
    >>> plaintxt = asciiporn.img2plaintxt('mario.jpg', scale = 0.5, invert = True)
    >>> print( plaintxt )

    ... b/w img w/ colors inverted.  may look funny now :/
        but it'll b normal when pasted document

################################################################################
PLOT USAGE:

################################################################################
RECENT CHANGELOG:
  rewrote 3d plotter
  fixed more 64bit issues
20081123
  fixed bug where 64bit  gets truncated to 32 on 32bit machine
  256 color support
20081119
  fixed bugs in setup.py
