Overview

The idea is to parse ASCII art images, embedded in reST documents and output an image. This would mean that simple illustrations could be embedded as ASCII art in the reST source and still look nice when converted to e.g. HTML

Installation

To install aafigure, you need to have administrator rights on your system (be root), and setuptools (often packaged as python-setuptools) must be installed.

Type "python setup.py install" to install aafigure. Alternatively, type "python setup.py develop" to only install a reference to the aafigure source directory. This is useful if you want to hack the source.

After that, the aafigure directive will be available site-wide.

Implementation

Files:

aafigure.py

ASCII art parser. This is the main module.

aafigure_directive.py

Implmements the aafigure Docutils directive that takes these ASCII art figures and generates a drawing.

aa.py

ASCII art output backend. Intended for tests, not for the end user.

pdf.py

PDF output backend. Depends on reportlab.

pil.py

Bitmap output backend. Using PIL, it can write PNG, JPEG and more formats.

rst2html.py

Patched version that adds the aafigure Docutils directive.

svg.py

SVG output backend.

The aafigure module contains code to parse ASCII art figures and create a list of of shapes. The different output modules can walk trough a list of shapes and write image files.

Usage

./rst2html.py README.txt >README.html

This results in the README.html file and a .svg file for each aafigure.

Display the resulting README.html file in a SVG capable browser. It has been tested with Firefox 1.5.

Short introduction

This code in a reST document that is processed with the enhanced rst2html.py looks like this:

.. aafigure::

    -->

Which results in an image like this:

The aafigure directive has the following options:

• :scale: <float> enlarge or shrink image

• :line_width: <float> change line with (svg only currently)

• :format: <str> choose backend/output format: 'svg', 'png', all bitmap formats that PIL supports can be used but only few make sense. Line drawings have a good compression and better quality when saved as PNG rather than a JPEG. The best quality will be achieved with SVG, tough not all browsers support this vector image format at this time.

• :foreground: <str> foreground color in the form #rgb or #rrggbb

• :background: <str> background color in the form #rgb or #rrggbb (not for SVG output)

• :fill: <str> fill color in the form #rgb or #rrggbb

• :name: <str> use this as filename instead of the automatic generated name

• :aspect: <float> change aspect ratio. Effectively it is the width of the image that is multiplied by this factor. The default setting 1 is useful when shapes must have the same look when drawn horizontally or vertically. However, :aspect: 0.5 looks more like the original ASCII and even smaller factors may be useful for timing diagrams and such. But there is a risk that text is cropped or is draw over an object beside it.

  The stretching is done before drawing arrows or circles, so that they are still good looking.

• :proportional: <flag> use a proportional font instead of a monospaced one.

---- |         ___  ~~~|
     | --  ___|        |    ===
                       ~~~

--->   | | | | | |
---<   | | | | | |
---o   ^ V v o O #
---O
---#

+-----+   XXX  /--\     --   |
|     |   XXX  |  |    /    /
+-----+   XXX  \--/   |   --

Hello World  dd d
                d

"Hello World"  dd d
                  d

Hello World  dd d
                d

* { }

TODO

• Symbol detection: scan for predefined shapes in the ASCII image and output them as symbol from a library

• Symbol libraries for UML, flowchart, electronic schematics, ...

• The way the image is embedded is a hack (inserting a tag trough a raw node...)

• Search for ways to bring in color. Ideas:

  • have an :option: to set color tags. Shapes that touch such a tag inhertit it's color. The tag would be visible in the ASCII source tough:

    .. aafigure::
        :colortag: 1:red, 2:blue
    
        1--->  --->2

  • :color: x,y,color but counting coordinates is no so fun

  drawback: both are complex to implement, searching for shapes that belong together. It's also not always wanted that e.g. when a line touches a box, both have the same color

• aafigure probably needs arguments like font-family, ...

• Punctuation not included in strings (now a bit improved but if it has a graphical meaning , then that is chooses, even if it makes no sense), underlines in strings are tricky to detect...

• Dotted lines? ...

• Group shapes that belong to an object, so that it's easier to import and change the graphics in a vector drawing program.

• Path optimizer, it happens that many small lines are output where a long line could be used.

License

BSD

Tests

To compare input and output, look at the sources of this file.