https://github.com/ravenexp/aatrace

Yet another ASCII-art generator
https://github.com/ravenexp/aatrace

Last synced: 18 days ago
JSON representation

Yet another ASCII-art generator

• Host: GitHub
• URL: https://github.com/ravenexp/aatrace
• Owner: ravenexp
• Created: 2012-05-14T16:16:35.000Z (over 12 years ago)
• Default Branch: master
• Last Pushed: 2012-09-01T21:15:23.000Z (about 12 years ago)
• Last Synced: 2024-10-10T19:38:58.693Z (about 1 month ago)
• Language: C
• Size: 168 KB
• Stars: 6
• Watchers: 2
• Forks: 1
• Open Issues: 0
• Metadata Files:
  • Readme: README

Awesome Lists containing this project

README

        
aatrace - Yet another ASCII-art generator

1. Building

$ make

while (!works)

      tweak(Makefile);

2. Program usage

Using convenience wrapper script:

$ ./aaconvert.sh [OPTIONS] image.pgm

Generates image.diff.pgm, image.ascii.txt and image.ascii.pgm files

in the current directory.

image.diff.pgm is an intermediate differentiated image output,

image.ascii.txt is the text output and image.ascii.pgm is the image output.

When one or more command line options are specified they are embedded in

the output file names as additional suffixes before the final file type.

$ ./aaconvert.sh -l 5 image.pgm

generates image.diff.l5.pgm, image.ascii.l5.txt and image.ascii.l5.pgm.

OPTIONS

A. Differentiation options

-l  - differentiated image levels scaling

Adjusts differential edge map "brightness".

Specify small integer in the range of 1..20 (approx).

1 is "normalized" is the sense that it never clips

the values (but is too dark for most images).

The current default is 6.

-d  - differentiation kernel (size)

Adjust the detail/noise sensitivity.

Available kernel sizes: 2, 3, 4.

The default is 3 (Sobel operator).

Specifying 1 skips the differentiation step entirely (aalib-style).

-t  - differentiation map feature detection threshold

Differentiation map features weaker than threshold are removed

from the output. Adjust the detail/noise sensitivity.

Thresholding is applied after scaling transform so that the output value

range only depends on the threshold.

Specify an integer in the range 0..255.

The current default is 64.

B. Matching options

-m  - match method

Selects the character matching algorithm used.

Available options:

 1 - Minimize SAD (sum of absolute differences)

 2 - Minimize weighted SAD + ASD (absolute sum of differences)

The current default is 2.

Notes:

 * MIN(SAD) is the tried and proven method used in video motion compensation.

 * MIN(SAD + ASD) tries to preserve perceptible tile brightness

   as well as its shape.

-W , - SAD/ASD weight ratio

 and  parameters tune the SAD+ASD match algorithm.

Specify two integers separated by comma ','.

It's NOT a real number, but rather a ratio of weights /.

Zeros are allowed and meaningful (0 and infinity).

The matching algorithm looks for MIN(*SAD + *ASD).

The default values are  = 5 and  = 1.

C. Offset search options

-s  - offset search method

Selects the offset searching algorithm.

Available options:

 1 - No offset search is performed. The tiles are matched exactly where they

     are in the source image.

 2 - Diamond search. Additionally checks whether better matches can be

     obtained by offsetting the source image tile by 1 pixel along any axis

     ("diamond" pattern). Runs match search 5 times.

 3 - Box search. The same as diamond + the diagonal moves are checked

     ("box" pattern). Runs match search 9 times.

 4 - Area search. Implements arbitrary size Box search.

     The search area size is specified with -r option.

The current default is 1 - No search.

-r (|,) - area offset search range (pixels)

Only affects the Area offset search method.

Specifies the search range(s) in both directions.

Different ranges in horizontal and vertical directions can be

specified with a comma (,).

The current default is  = 2 ( = 2,  = 2) - 5x5 pixel area.

-c <1/0> - enable/disable search coverage test

Only affects offset search strategy.

Performs match score adjustment for off-center matches to improve

source image feature coverage by the character tiles.

Should only be disabled for search testing purposes.

The current default is 1 - enabled.

ENVIRONMENT VARIABLES

AAFONT environment variable overrides the default the font image.

2.1 Using the test utilities (plumbing)

Generate the differentiated image:

$ ./testdiff [-l ] [-d ] [-t ] image.pgm image.diff.pgm

Generate ASCII text file from the differentiated image:

$ ./testconv [OPTIONS] image.diff.pgm font/font8x16.pgm image.ascii.txt

OPTIONS ::=

[-m ] [-W ,] [-s ] [-c <1/0>] [-r (|,)]

Render ASCII text back into an image:

$ ./testrender image.ascii.txt font/font8x16.pgm image.ascii.pgm

'-' supplied as an argument uses stdin or stdout for inputs and

outputs respectively.

'--' option separator is required to use '-'.

font/font8x16.pgm is the VGA terminal font image supplied as a sample.

The font bitmap characters are stacked vertically starting from

the whitespace character (ASCII 0x20).

All image files are in the Portable GrayMap (PGM) format.

ImageMagick or netpbm may be used to generate compatible input(s) and

convert output(s) into something more usable.

3. Tweaking

Tweaking command line parameters:

Changing -l  adjusts the amount of detail (and noise) that makes

it into the final ASCII picture.

Check generated .diff.pgm file to see the effect of the adjustments.

Changing -d  adjusts the detail sensitivity level.

Heavily oversampled images require larger kernels (4),

while vector drawing and pixel art details are better preserved by

smaller kernels (2). 3 is a reasonable default.

Changing -t  adjusts weak detail/noise sensitivity level.

Raising the threshold over the default 64 results in cleaner image,

but it retains less features.

High threshold value can speed up conversion considerably by

removing unnecessary detail and simplifying match decision process.

Changing -m  affects the match search strategy:

  * SAD (1) looks for the most similar character representation.

  * SAD+ASD (2) tries to optimize for the overall perceptible similarity

                at the expense of larger small-scale errors.

Tweaking -W , weights ratio tunes SAD+ASD method

to pay more attention to shape (SAD) or overall brightness (ASD).

Due to the nature of the minimization problem, only the ratio of the weights is

significant, i.e. the default -W 5,1 is the same as -W 10,2.

-W 1,0 is the same as -m 1, but slower, -W 0,1 is pure ASD (like aalib).

Example:

$ ./aaconvert.sh -l1 -d1 -W0,1 test.pgm

Yields the result very similar to what aalib does.

It skips the differentiation (codes levels rather than edges) and

uses ASD (average level) for the match search.

Enabling offset search via -s 2(3,4) allows for better character matches

at the price of small spatial jitter. This usually results in visually

"cleaner" image. However, the search algorithm tends to avoid thin lines

at the edges of the image tiles by stepping away from them. Skipped lines

are not included in the match search often resulting in smaller match errors.

Search coverage test compensates for the edge skipping effect by

including not matched parts of the source tile in the total match error.

Stepping away from a feature results in the same match error as matching

it with black level.

The coverage test should always be enabled (default) when using offset search for

best output quality.

Note:

Diamond search (-s 2) checks 5 possible offsets for each tile,

resulting in 5x slowdown compared to direct matching.

Box (-s 3) search analyzes 9 neighboring locations, making it 9x slower.

Area (-s 4) search with the default range (-r 2) checks 25 tile locations.