Skip to content
A python library and command-line tool to handle ASCII-Art to Text conversions
Branch: master
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
examples Moved example files to subdirectory Jul 8, 2013
.gitignore Added test scripts and scenarios Jul 8, 2013
README.html moved test related scenarios and data files to test subdir Jul 8, 2013 Removed test code from Jul 8, 2013
decimal.charset Renamed digits.charset to decimal.charset Jul 8, 2013
hex.charset Initial code, charsets and user stories Jul 8, 2013


A python library and command-line pipe tool to handle ASCII-Art to Text conversions.


  • Encoding: convert from string to ascii-art.
  • Decoding: convert from ascii-art to string.
  • Customizable charsets: the user may specify a .charset file via the -c switch to select which characters will be supported. decimal.charset is used by default (digits 0-9), hex.charset is also provided (digits 0-9 and a-f, for hexadecimal base).
  • Illegal character indicators: Whenever an invalid ascii-art character (block) is encountered, it is replaced by a special indicator (? by default).
  • Illegal character line indicators: When a line with at least one illegal block is decoded, this indicator will be appended to it ( ILLEGAL by default).
  • Block error tolerance: Whenever an invalid ascii-art character (block) is encountered, the program can attempt to fix it buy matching it to a similar block character 'drawing'. The tolerance of the distance function is configurable by a parameter.
  • Variable line/block-line width: The pipe can handle lines of different widths (both in plaintext and ascii-art forms). Incase a single ascii-art block-line (typically 4 lines high) varies in its line widths, an error is thrown. The last line in a ascii-art block line (typically the 4th line in the plaintext) may be empty or at the exact correct width.


The program requires python 2.7.x, with no special libraries.


The program ( is a command-line pipe (receives input via stdin, outputs to stdout). It may do both encoding (string to ASCII art) and decoding (ASCII art to string) operations.

Detailed usage instructions (from python -h):

usage: [-h] [--charset CS] [--tolerance T] [--no-illegal]
                   [--invalid_char C]

Text <--> ASCII Art conversion pipe (stdin --> stdout)

positional arguments:
  {encode,decode}   encode: ascii-art --> text, decode: text --> ascii-art

optional arguments:
  -h, --help        show this help message and exit
  --charset CS      selects file CS as the ascii-art charset
  --tolerance T     conversion will tolerate errors of up to distance T
  --no-illegal      will not print the ILLEGAL suffix in-case of errors
  --invalid_char C  will use C to indicate an unrecognized ascii-art block

Critical errors (e.g. bad file formats, invalid spacing, etc.), trigger an exception, promptly terminating the program.


Encoding (decimal to ascii-art)

Encoding the decimal data in ex1_decimal.txt will yield the results found in ex1_art.txt:

python encode < ex1_decimal.txt > ex1_art.txt

Output (in ex1_art.txt):

    _  _  _     _  _ 
  ||_  _||_ |_| _||_ 
  ||_||_  _|  | _| _|
  |  | _|  |
  |  ||_   |

Decoding (ascii-art to decimal)

Decoding the ascii-art data in ex1_art.txt will yiedl the results found in ex1_decimal.txt:

python decode < ex1_art.txt > ex1_decimal.txt

Output (in ex1_decimal.txt):


Encoding from directly from stdin

Input may be written directly to the command line, and terminated by an EOF character (Ctrl+Z):

python encode

Output (same as ex2_art.txt):

 _  _  _  _  _  _  _
  | _||_   | _| _| _|  |
  ||_ |_|  ||_ |_ |_   |

    _  _  _     _  _  _
|_||_  _||_|  || | _| _|
  | _| _| _|  ||_||_  _|

Decoding erroneous input

Incase of decoding errors, a '?' character replaces all unrecognized characters, and an ' INVALID' string is appended to the end of the decoded line. In ex2_art_error1.txt, the 2 digits in the first line have their middle line removed:

python decode < ex2_art_error1.txt > ex2_decimal_error1.txt


7267???1 ILLEGAL

Controlling error indications

We can customize the error indication character (default '?') to some other character (in this example we will use '_') using the --invalid_char option, and remote the ' ILLEGAL' suffixes using the --no-illegal switch:

python decode --invalid_char _ --no-illegal < ex2_art_error1.txt



Automatically fixing errors

We can instruct the program to automatically attempt to fix erroneous block characters (ascii-art), by replacing these with visually-similar blocks. For example, in the erronous input inside ex2_art_error1.txt, the program will recognize the bad '2' characters in the first line are only one character apart from the good representation of '2'. By increasing the error tolerance from the default 0 to 1 (--tolerance 1), we will automatically fix these errors:

python decode --tolerance 1 < ex2_art_error1.txt > ex2_decimal_error1_recovered.txt

Output (in ex2_decimal_error1_recovered.txt):


Using different charsets (hexadecimal)

We can select charsets different from the default decimal (decimal.charset), by using the --charset switch. In this example, we will use a hexadecimal charset (0-9 and a-f):

python encode --charset hex.charset < ex3_hex.txt > ex3_art.txt

Input (in ex3_hex.txt):


Output (in ex3_art.txt):

    _  _        _  _  _
 _||_ |_| _||_ |_ |_ |_
|_||_ | ||_||_||_ |_ |

 _  _  _  _  _  _  _  _  _  _
 _| _|  |  ||_||_| _|| | _|| |
|_  _|  |  | _| _||_ |_||_ |_|

 _     _  _
|_  _||_| _| _|
|_||_| _||_ |_|

 _  _  _  _  _  _  _
|_ |_ |_ |_ |_ |_ |_
|  |  |  |  |  |  |

All other flags previously exemplified work exactly the same with non-default charsets such as this.


  • Testing is done via the tool, which compares the result of an encoding or decoding operation on an input file versus an expected output file.
  • Test operation: If all lines of the operation result are identical to the expected output file, the test is considered successful. Otherwise, errors are enumerated on a per-line basis, and reported to the runner.
  • Test scenarios: each test scenario is specified by a JSON entry, which includes the following data:
    • test scenario alias (for printing)
    • arguments (e.g. encode --tolerance 1)
    • input file
    • expected output file
    • user comments (optional)
  • Test results: summarized results are dumped on a per-scenario basis to stdout upon test completion. Detailed results may be written into a json file via the parameter -r <results_file>. Progress can be echoed to console via the -v (verbose) parameter.

Test tool syntax (from python -h):

usage: [-h] [-t TESTS_FILE] [-v] [-r REPORT_FILE] [--whitespace-exact]

ASCII Art test utility

optional arguments:
  -h, --help          show this help message and exit
  -t TESTS_FILE       test scenarios file
  -v                  verbose output
  -r REPORT_FILE      output results to report file
  --whitespace-exact  will NOT ignore whitespace-only lines if specified

Charset file format

ascii-art character sets are specified via a text file containing the following data fields:

  • block-width: specifies the width in characters of each ascii-art block character (included charsets use 3).
  • block-height: specifies the height in lines of each ascii-art block character (included charsets use 4).
  • string-characters: the N characters to be used in plaintext form (regular characters, i.e. 1234567890 for decimal digits)
  • block-drawings: the ascii-art blocks corresponding to the above string-characters. All block-height lines must be exactly block-width characters wide. All N block characters must be of exact dimensions block-width * block-height, resulting in exactly N * block-width * block-height being required for this field.

All the above fields are separated by a newline character (\n).

You can’t perform that action at this time.