8 The idea is to parse ASCII art images, embedded in reST documents and output
9 an image. This would mean that simple illustrations could be embedded as
10 ASCII art in the reST source and still look nice when converted to e.g. HTML
16 To install aafigure, you need to have administrator rights on your
17 system (be root), and ``setuptools`` (often packaged as
18 ``python-setuptools``) must be installed.
20 Type "``python setup.py install``" to install aafigure.
21 Alternatively, type "``python setup.py develop``" to only install a
22 reference to the aafigure source directory. This is useful if you
23 want to hack the source.
25 After that, the ``aafigure`` directive will be available site-wide.
34 ASCII art parser. This is the main module.
36 ``aafigure_directive.py``
37 Implmements the ``aafigure`` Docutils directive that takes these
38 ASCII art figures and generates a drawing.
41 ASCII art output backend. Intended for tests, not for the end user.
44 PDF output backend. Depends on reportlab.
47 Bitmap output backend. Using PIL, it can write PNG, JPEG and more formats.
50 Patched version that adds the ``aafigure`` Docutils directive.
56 The ``aafigure`` module contains code to parse ASCII art figures and create
57 a list of of shapes. The different output modules can walk trough a list of
58 shapes and write image files.
65 ./rst2html.py README.txt >README.html
67 This results in the ``README.html`` file and a ``.svg`` file for each
70 Display the resulting ``README.html`` file in a SVG capable browser. It has
71 been tested with Firefox 1.5.
77 This code in a reST document that is processed with the enhanced ``rst2html.py``
84 Which results in an image like this:
90 The ``aafigure`` directive has the following options:
92 - ``:scale: <float>`` enlarge or shrink image
94 - ``:line_width: <float>`` change line with (svg only currently)
96 - ``:format: <str>`` choose backend/output format: 'svg', 'png', all
97 bitmap formats that PIL supports can be used but only few make sense. Line
98 drawings have a good compression and better quality when saved as PNG
99 rather than a JPEG. The best quality will be achieved with SVG, tough not
100 all browsers support this vector image format at this time.
102 - ``:foreground: <str>`` foreground color in the form ``#rgb`` or ``#rrggbb``
104 - ``:background: <str>`` background color in the form ``#rgb`` or ``#rrggbb``
105 (*not* for SVG output)
107 - ``:fill: <str>`` fill color in the form ``#rgb`` or ``#rrggbb``
109 - ``:name: <str>`` use this as filename instead of the automatic generated
112 - ``:aspect: <float>`` change aspect ratio. Effectively it is the width of the
113 image that is multiplied by this factor. The default setting ``1`` is useful
114 when shapes must have the same look when drawn horizontally or vertically.
115 However, ``:aspect: 0.5`` looks more like the original ASCII and even smaller
116 factors may be useful for timing diagrams and such. But there is a risk that
117 text is cropped or is draw over an object beside it.
119 The stretching is done before drawing arrows or circles, so that they are
122 - ``:proportional: <flag>`` use a proportional font instead of a monospaced
128 The ``-`` and ``|`` are normally used for lines. ``_`` and ``~`` can also be
129 used. They are slightly longer lines than the ``-``. ``_`` is drawn a bit
130 lower and ``~`` a bit upper. ``=`` gives a thicker line. The later three line
131 types can only be drawn horizontally.
144 It is also possible to draw diagonal lines. Their use is somewhat restricted
145 tough. Not all cases work as expected.
150 | - + | - + | - + / -
151 / / / / / / / / / / -- |/| / +
152 | | | + + + - - - / / \ - \|/ |\
154 | | | + + + - - - \ \ / - /|\ |/
155 \ \ \ \ \ \ \ \ \ \ -- |\| \ +
156 | - + | - + | - + \ -
159 And drawing longer diagonal lines with different angles looks ugly...
189 Boxes are automatically draw when the edges are made with ``+``, filled
190 boxes are made with ``X`` (must be at least two units high or wide).
191 It is also possible to make rounded edges in two ways::
193 +-----+ XXX /--\ -- |
195 +-----+ XXX \--/ | --
199 +-----+ XXX /--\ -- |
201 +-----+ XXX \--/ | --
206 Upper case characters generate shapes with borders, lower case without border.
207 Fills must be at least two characters wide or high. (This reduces the chance
208 that it is detected as Fill instead of a string)
212 A B C D E F G H I J K L M
213 AA BB CC DD EE FF GG HH II JJ KK LL MM
214 AA BB CC DD EE FF GG HH II JJ KK LL MM
216 aa bb cc dd ee ff gg hh ii jj kk ll mm
217 aa bb cc dd ee ff gg hh ii jj kk ll mm
219 N O P Q R S T U V W X Y Z
220 NN OO PP QQ RR SS TT UU VV WW XX YY ZZ
221 NN OO PP QQ RR SS TT UU VV WW XX YY ZZ
223 nn oo pp qq rr ss tt uu vv ww xx yy zz
224 nn oo pp qq rr ss tt uu vv ww xx yy zz
226 Complex shapes can be filled:
236 The images may contain text too. There are different styles to enter text:
240 Bby default are repeated characters detected as fill::
252 Text between quotes has priority over any graphical meaning::
262 ``"``, ``'`` and ``\``` are all valid quotation marks. The quotes are not
263 visible in the resulting image. This not only disables fills (see below), it
264 also treats ``-``, ``|`` etc as text.
268 The ``:textual:`` option disables horizontal fill detection. Fills are only
269 detected when they are vertically at least 2 characters high::
297 - Symbol detection: scan for predefined shapes in the ASCII image
298 and output them as symbol from a library
300 - Symbol libraries for UML, flowchart, electronic schematics, ...
302 - The way the image is embedded is a hack (inserting a tag trough a raw node...)
304 - Search for ways to bring in color. Ideas:
306 - have an :option: to set color tags. Shapes that touch such a tag
307 inhertit it's color. The tag would be visible in the ASCII source tough::
310 :colortag: 1:red, 2:blue
314 - ``:color: x,y,color`` but counting coordinates is no so fun
316 drawback: both are complex to implement, searching for shapes that belong
317 together. It's also not always wanted that e.g. when a line touches a
318 box, both have the same color
320 - aafigure probably needs arguments like ``font-family``, ...
322 - Punctuation not included in strings (now a bit improved but if it has a
323 graphical meaning , then that is chooses, even if it makes no sense),
324 underlines in strings are tricky to detect...
326 - Dotted lines? ``...``
328 - Group shapes that belong to an object, so that it's easier to import and
329 change the graphics in a vector drawing program.
331 - Path optimizer, it happens that many small lines are output where a long
343 To compare input and output, look at the sources of this file_.
350 Different arrow types:
411 No not really, yet. But you get the idea.
416 +---------+ +---------+ +---------+
417 |Object 1 | |Object 2 | |Object 3 |
418 +----+----+ +----+----+ +----+----+
427 X------------------------>X
432 X<------------------------X
440 +---------+ +---------+ +---------+
441 | Shape | | Line | | Point |
442 +---------+ +---------+ 2 +---------+
443 | draw +<--------+ start +----O+ x |
444 | move +<-+ | end | | y |
445 +---------+ \ +---------+ +---------+
456 /-----------\ yes /----------\
457 -->| then this |--->*--->| and this |
458 + / \-----------/ |no \----------/
462 + \ /---------\ V /------\
463 -->| or that |----->*------->| Done |
468 It would be cool if it could display simple schematics.
474 O->---+ R1 +---o-->-----O
476 Vin| 100k ----- C1 | Vout
479 O---------------o--------O
481 .. - Resistor should not be filled -> can be solved by symbol detection
483 - Capacitor not good, would prefer ``--||--`` -> symbol detection
489 ---+ +--- --+ +-- --+ +-- -+ +- b|/
490 |\| |/| | | +---+ --+
495 -+- -+- -+- | | c\ /e
501 - Caps not optimal. Too far apart in image, not very good recognisable in
502 ASCII. Space cannot be removed as the two ``+`` signs would be connected
503 otherwise. The schematic below uses an other style.
505 - Arrows in transistor symbols can not be drawn
507 Here is a complete circuit with different parts:
519 +-----+-------------+-----+
522 | P3.3 +--------------+
523 SDA/I2C O---+ P2.0 | |
525 | MSP430F123 | +----+ b|/ V1
526 SCL/I2C O---+ P2.1 P3.4 +---+ R1 +---+ PNP
529 | | o----+ R3 +---O TXD/RS232
531 +-----+---------------+---+ | 1k
533 | | +----+ R2 +---O RXD/RS232
536 GND/I2C O---o-----+----o----------o-----------o--------------------O GND/RS232
538 =+= | ----- 1u | ----- 10u
539 | ----- 5V +---+---+ ----- 16V
541 +----o------+out in+-------o----------o---+ +---O RTS/RS232
545 +---+ +---O DTR/RS232
555 A |___| |___| |_________| |______
557 B |_____| |______| |________XX XX__
559 +-------------------------------------> t
561 Here is one with descriptions:
571 |____| |_____..._________|
572 ______ _____ _..._ _____
574 |____| |_____| |_____|
578 | 'sh_in' | 'sh_in' | 'sh_in
579 'sh_out' 'sh_out' 'sh_out'
586 Benfords_ distribution of the sizes of files on my hard drive:
588 .. _Benfords: http://en.wikipedia.org/wiki/Benfords_law
596 1 +------------------------------------------------------------> 31.59%
597 2 +-------------------------------> 16.80%
598 3 +-----------------------> 12.40%
599 4 +-----------------> 9.31%
600 5 +--------------> 7.89%
601 6 +-----------> 6.10%
606 +---------+---------+---------+---------+---------+---------+--->
629 "Week" | 1 | 2 | 3 | 4 | 5 |
630 ------------+----------------------------------------
632 "Task 2" | EEEEEEEEEEEE
633 "Task 3" | GGGGGGGGZZZZZZZZZZ
634 "Task 4" |DD DD DD DD