Index of /sandbox/aafigure

[ICO]NameLast modifiedSizeDescription

[PARENTDIR]Parent Directory   -  
[DIR]aafigure/ 2018-06-17 08:52 -  
[TXT]makefile 2018-06-17 08:52 369  
[TXT]setup.py 2018-06-17 08:52 1.6K 

aafigure README

aafigure README

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:

Lines

The - and | are normally used for lines. _ and ~ can also be used. They are slightly longer lines than the -. _ is drawn a bit lower and ~ a bit upper. = gives a thicker line. The later three line types can only be drawn horizontally.

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

It is also possible to draw diagonal lines. Their use is somewhat restricted tough. Not all cases work as expected.

And drawing longer diagonal lines with different angles looks ugly...

Arrows

Arrow styles are:

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

Boxes

Boxes are automatically draw when the edges are made with +, filled boxes are made with X (must be at least two units high or wide). It is also possible to make rounded edges in two ways:

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

Fills

Upper case characters generate shapes with borders, lower case without border. Fills must be at least two characters wide or high. (This reduces the chance that it is detected as Fill instead of a string)

Complex shapes can be filled:

Text

The images may contain text too. There are different styles to enter text:

direct

Bby default are repeated characters detected as fill:

Hello World  dd d
                d

quoted

Text between quotes has priority over any graphical meaning:

"Hello World"  dd d
                  d

", ' and \` are all valid quotation marks. The quotes are not visible in the resulting image. This not only disables fills (see below), it also treats -, | etc as text.

textual option

The :textual: option disables horizontal fill detection. Fills are only detected when they are vertically at least 2 characters high:

Hello World  dd d
                d

Other

* { }

TODO

License

BSD

Tests

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

Simple tests

Different arrow types:

Boxes and shapes:

Flow chart

UML

No not really, yet. But you get the idea.

Electronics

It would be cool if it could display simple schematics.

  • Capacitor not good, would prefer --||-- -> symbol detection

  • Diodes OK

  • Caps not optimal. Too far apart in image, not very good recognisable in ASCII. Space cannot be removed as the two + signs would be connected otherwise. The schematic below uses an other style.

  • Arrows in transistor symbols can not be drawn

Here is a complete circuit with different parts:

Timing diagrams

Here is one with descriptions:

Statistical diagrams

Benfords distribution of the sizes of files on my hard drive:

Just some bars:

Schedules