ascii-art-cli 1.4.0
ASCII art generator with multiple customization parameters
License: MIT
Requires Python: >=3.7,<4.0
Keywords: cli,console,ascii,art,font,image

# ![ascii-art](https://raw.githubusercontent.com/dawsonbooth/ascii-art/master/logo.png)

[![pypi version](https://img.shields.io/pypi/v/ascii-art-cli.svg?style=flat)](https://pypi.org/pypi/ascii-art-cli/)
[![downloads](https://pepy.tech/badge/ascii-art-cli)](https://pepy.tech/project/ascii-art-cli)
[![build status](https://github.com/dawsonbooth/ascii-art/workflows/build/badge.svg)](https://github.com/dawsonbooth/ascii-art/actions?workflow=build)
[![python versions](https://img.shields.io/pypi/pyversions/ascii-art-cli.svg?style=flat)](https://pypi.org/pypi/ascii-art-cli/)
[![format](https://img.shields.io/pypi/format/ascii-art-cli.svg?style=flat)](https://pypi.org/pypi/ascii-art-cli/)
[![license](https://img.shields.io/pypi/l/ascii-art-cli.svg?style=flat)](https://github.com/dawsonbooth/ascii-art/blob/master/LICENSE)

## Description

Named as such, this package is a command-line ASCII art generator written in Python. There is a variety of parameters which are detailed below.

## Installation

With Python installed, install the package from PyPI with the following command:

```bash
python -m pip install ascii-art-cli
```

This package is not to be confused with [ascii_art](https://pypi.org/project/ascii_art/) or other various ASCII art packages.

## Usage

This is a command-line program, and can be executed as follows:

```bash
ascii-art [-h] [--width WIDTH] [--height HEIGHT] [--chars CHARS] [--font FONT] [--invert] [--normalize] input
```

Positional arguments:

```txt
  input            Path to image from which ASCII art will be generated
```

Optional arguments:

```txt
  -h, --help       show this help message and exit
  --width WIDTH    Character width of ASCII art
  --height HEIGHT  Character height of ASCII art
  --chars CHARS    String containing characters to be seen in ASCII art
  --font FONT      Font for calculating the character weights
  --invert         Whether the ASCII output color is inverted
  --normalize      Whether the weights of the provided ASCII characters are normalized
```

Example:

```bash
ascii-art examples/images/einstein.jpg --width 100 --height 50 --font "Courier" --invert --normalize
```

```txt
,;+;;+;;;,?;?;;;,,,,,,;,;',,'',;%S;;;%SS%SSSSSSSSSSSSSSSSSSSSSSSSS%%%%%%??%%%%;'S+..    .          .
+;;;?;+;,++;;,,,,,;,,,,,,,,,';+%S,,%S%SS#SSSSSS####S#S##S##SSSSSSS%S%%%%%%%S%SS+'%'.
?+;;,;+;;,;+;;;,,,,;,,,','',;%%%',S%S%SSSSSS#SSSS#SSSSS####SSS#SSSSS%S%%S%%%%S%%%;;'.            ..
%+;%+;?++;;,,;,,,,,,',,',,;+,%?;'?;%SSSSS#SSSSS##SS######@##SSSS#SSSS%S%S%%%%%S%%'%''        .... .
?????;;??;;;+,,+,,,,''',;+;;;;;',%%%SSS#######S###########SSS##SSSSSSS%SS%%%%SSS%?',;,   .    ...
?+;??++;;+;;;,,,,,''',,;%?%%,,''%,%SSSS#######S#####@#######SSS%#SSSSSS%%%%%%SSSS%;?.'''.          .
;?%;;;+;;+;,,,,,,''',;S?;,',;,'+,S%?%SSS#@###SS########@#SSSS#SSSSSSSS%SS%%%%S%S%S?%'  .'    .
???;;;++,;+;,;',''',%S'?;,+,,?.;?%S%%SSS#@############S###SSSSSSSSSSSSSSSS%%SSSSS%+,,.. ',    .
??+?;;%++;;,,,,,,;';%',,;;;';%';%'.',+,SSS###SSS##SSS%,',SS%S#%SSSSSSSSSSS%SS%SS%%%,;,.  .'
%;+;?+;+;;;+,,,,,''?''?;?+,;%?.''.'',%SS##S#SSS##SSSSSS?;,;%??SSSSSSSSSSSSSSSSSSS%?%;'+'..'.
S????;;;;;;;;;,'',,%,;+,%?,,%;'%;;%%%%SSS##@SSS##SS###SSSSSSSSSSSSS%SSSSSS%SSSSSS%?+;,''.'.'
?,?+;;?;;;,,;,,,'+,''.%%;,,?%+.;?SSSSS%SSS#S#@###@####S##SSSSSSSS%SSSSSSSSSSSSS%%%????'',. .'..    .
,S;,;;??;;;;,',,''',.,,%;'';%,.%%SS%%%S%%SS####@@#SS#SS#SSSS#SSSSSSSSSSSSSS%SSS%%%%,;?;+.,   .
%%?;;+%;;;+,,,',.,...,;;,',;?',%SS%%%??SS?%S#@@###SSSS%%+,;%SS#SSS%SSSSSSSSSSSSSSS%%,,+?;,,.   .
S?%;+;+;,,,,,';'.'.'',%,,,'+%''?S%,,?+?S%%,?S#@#S#SSSSS?+%%%+%SSSS%SSSSSSSSSSSSSSS%%%;?;%%' .
S,+,;;;+,,,,''......',%''',;?',%?,'##;,?;S?'S@##SSS%%%;';.,S%%SSSS%SSSSS%SSSSSSSSS%S?;%;%;,S.      .
%%?;+,;,;,''.'......''%',',%,';%%'+S...;#%%'S#SSS%SS%?#S...,?%%SSS%SSS%S%SSSSSSSS%+%%?;;%%;,';
,+?;;,;,,''''.... ..',?,'''%'';%S,;%,'%%;%,%SSSSS%#S%SSS...S%SSSSSSSSSS%SSSSSSS%S%%%??%?;+;;..,.
,%';,,;,''''......';.';.',.;'';%,;''%?S;SS'%SSSSS%SS%%%?%%%?+%SSSSSSSSS%%%SSSS%%%%%?%;?%%;,++  ;
%%',';;,',''....'.., ;%.''.;.,+,?%?,%%%%%,,%SSSSSSSS?%S%%%%%%%S%%SSS%SSS%%SSSS%%%%%%%%%,%;;,;;
S%',,'.;''''...,.....;,'''.'.,%;%%%%%%%%?';SSS%SSSSSSS%%SSSSSS%%SSSS%SS%%%%S%%%%;;;%%%%%+S?'+,' '
%;..''''','....'....,.,'.'...?%%%SSSS%SS''%SS%%%SSSS#SS#SSSSSSSS%%S%%%S%%%%%%%??S%',+%%%%?%+'+.. .
%,. ...''.''...'...;'',..S...,%SSSSSSSS%'%SSSS%?%SSS###SSSSSSSSSSSSS%%%%%%%%%%;%%S;%;;%%%%%%%?,. '
+'  ....''......'.?,''...,...%S#SS?SSS%,+SSSS%%%%SS#SS#S@#SSSS##SSS%%%%%%++;%?%SS%;?;.%%SSS%%?;''..
?.  .  .........'.''.....'...%SSSS%SS%S,SS##SSS%?%S##SS########SSSSS%%%%%+;%;SSSSSS.%%%%SSS%;%%',.
,. ... ........'... ...'''...;#SS%SS%#';SS##@SS%%%%SS@@#S####S##SSS%%+%%?;,%%SSSS%%S%S.%SSSS%%S+'.
.... .. . .........'..'...'..+%S%%%S#S,,%S#@#SS%SS%%SS@#####S##SS#SS?;%%%;;%S#SSS%SS%S%;SSSS%?S%' .
?, ....  .... ....'.......,..;?%%SS##',',SSSSS%SSSS?S#S##@#S#S#SSSSS%;%%?%++%%%SS%%SS%%;S#SS,%S%;.'.
,,.... . ..  .. .........,,..++;%S##SS?'.;%%%;#S@%%%SSSS####SSSSS+SS%?%%?%;%S#%S%S%SS%%+SSSS;;S%?.
%;.. ....   .. ... ..%'+S''..+%;SSSS%%?SSSS#SS#%S%SSSS#S%S#SSSSSSSSS+?%+%%;SSS%S;SSS%S;S#SSS?+S;''.
;,  %#... .S.  ..... .. '''..%S;%SSSSSSS#S#S%SS#SSSS%SSSSSSSSSSSSSSS%%%%%%,SSS?;??%S%%%SSSSS,,%, '..
',   .........  ... .  .,''..%S;S%S%SS@@SSSS%S##S#S#SSSSSSSSSSSSSSSS+%%?%?+SSS%,%%%?%+SS%S%%,%; ' ..
,' .   . .  ....... .....'...;S,%,?SS%S#%S#SS#SSSS##%SSSSS+SSSSSSSS%;%%%%+%SS%??.'S%%%%;;SS%,'......
'   ...#.  .. .  .. .....'...,%;%?;;%%%SS#SSSS%S#%%%S%SSSSSSSSSSSSS%,S%%%;.S%?' ..;S;,%.'%,. .......
'  . . ......  .... .........'%;%%?,',,?;%;%++S%,,%,?S%#SS%SSSSSSSS%?%S%%%'        .'.  .;'.........
.  ..  . ...   ...............%%%SS;,.'.,'?';,,+SS,'+,;'SSSSSSSSSSS%;SS%+,'            . ...........
   ..   ..  ....... ..........%%'SSS%,,,?;%%?%%%%%;%,..;;SSS#SSSSSS%,SS%+'        .   . ......'....'
        . ..... ...............+%;SSS?.%S%%S%S%%%%%?''++%%?SSSSSSSS?SS%,           . ... .....'..',,
     .    . .  .......'........%S,SS#%.%%%%%%%S%S%?,,%SS#%?SS%SSSSS,S%,         .. ..... .......'',,
         .......................%S?##S.S#%S%S%%;SS;%%%%SSS%SS%SSSS+SS.              ... ....'. ''+,'
       . . ... ........'........'S+S#S.;SS%%;%%+#,,+?%S#SS%S%%SSSS%S  .       .   ...  .......',+,';
            ..'..................;SS#S.+S#SS%;;%S;,,%SSS#SSS?S#S%,%.       .   . .... ..... .,'+,,',
          ',,''''..........'......S'#S.'%@S%%?;%%';%S%SSSSSS;SS%+. .  .  .  .   .  .. . ....,,;,';,,
      . ,,,,,,','............'....'SSS,.%SS+%%%S;%S%SS##SS#SS#S?...      .. .  .... ..... ',;,,';,',
      ,,,',,,,,'''..........'''....%,SS.;%S%%?S%;%SS#S###SS%SS'..   ..   . .  . .   .   .'',++,;,;;,
    ,,,,,,,,,,,',.'.........''''....'?S%.?%?S%?,SS#SSS###SSSS....  ...   .. ..... .. ...';+%?,;,'','
. ,,,;,,,,,,,,,,,'''...''''''''''.....?S..%%%%%S##SSSS#S#S%........     .  .......   ..,,,,',;,;'''.
',,,,,,,,,,',,,,,','....'''''''''......%%..;+;SS@S#SSSSSS,.................... ...   ''',,,',;;+',..
,,,,,;,,,,,',,;,,,'''.''.'''''''''......%%+,%####S####S%............ ...........   .'',;;;'+,;';''..
,;,,,;,,,,,,;,,,;,,''.'''''''''..''......?%SSSSSS#SSS%............ ....'........  ..,,,,',,%;,'''..'
```

By default, the command will output the generated ASCII art to the console. If instead you would like to output to a file, feel free to use the redirection `>` operator. More info on that [here](https://linuxcommand.org/lc3_lts0070.php).

Feel free to [check out the docs](https://dawsonbooth.github.io/ascii-art/) for more information on how to use this package.

## License

This software is released under the terms of [MIT license](LICENSE).