Asciiville is where you go for ASCII Art, animations, and utilities. The Asciiville project provides integration and extension of several packages as well as providing convenience commands to invoke a variety of components used to display ASCII Art, animations, and text based utilities to perform common operations in a text-only environment.
Asciiville includes nearly 1,000 works of ASCII and ANSI Art!
Table of Contents
Click here to expand/collapse
Overview
See the Features section for an overview of the features and facilities available in Asciiville.Asciiville Ascii Art Galleries
The Asciiville project includes many curated Ascii Art galleries. These include hundreds of high resolution Ascii Art files created by Asciiville author and artist, Dr. Ronald Joe Record. The Asciiville package, when installed, provides the following Ascii Art galleries located in the default Ascii Art Gallery folder /usr/share/asciiville/art/:
Art - A collection of fine art transformed into Ascii Art Doctorwhen - Some of Doctor When's fantastic art Dragonflies - Photos of dragonflies converted to Ascii using Asciiville tools Fractals - Images of fractals converted to Ascii using Asciiville tools Friends - Photos of friends and family converted to Ascii using Asciiville tools Iterated - Images made with iteration converted to Ascii using Asciiville tools Lyapunov - Lyapunov fractals converted to Ascii using Asciiville tools Nature - Photos of nature converted to Ascii using Asciiville tools Owls - Photos of owls converted to Ascii using Asciiville tools Space - Photos of space converted to Ascii using Asciiville tools Vintage - Traditional Ascii Art Wallpapers - Pretty wallpapers converted to Ascii using Asciiville tools Waterfalls - Photos of waterfalls converted to Ascii using Asciiville tools
All of these galleries may be viewed using the menus in the asciiville command. Asciiville users can add their own custom galleries using the conversion and generation tools provided by Asciiville. Custom menus added to the Ascii Art Gallery folder will automatically appear in the asciiville menu selections.
Beginning with Asciiville version 1.4.0 release 2, Asciiville will ship with gzip compressed ascii art gallery files. If you wish to compress your current pre-1.4.0r2 Asciiville ascii art gallery files then download and install show_ascii_art. Install the updated show_ascii_art by copying it to /usr/bin/ with the command sudo cp show_ascii_art /usr/bin.
When creating custom ascii art galleries for use with Asciiville, compression is optional but can be used to reduce the disk size of ascii art files. When choosing to compress ascii art files, a gallery’s files must be compressed with gzip:
cd /path/to/gallery
sudo gzip *.ascClick here to View a Gallery of Ascii Art
Asciiville Commands
See the Commands section for details on the Asciiville commands.Quickstart
See the Quickstart section for details on getting started quickly with Asciiville.Requirements
Asciiville can be installed on Arch Linux, Debian based Linux systems, and RPM based Linux systems using the platform native packaging format.
Apple macOS users can install Asciiville manually using the provided installation script and Darwin distribution archive.
If no native packaging format is available, Linux users can install Asciiville manually using the provided installation script and Linux distribution archive.
Installation and initialization require administrative privilege. The ascinit command, executed after installing Asciiville, installs several packages and therefore requires access to the Internet along with administrative privilege (e.g. sudo privilege).
All of the following dependencies/requirements are automatically installed if needed when using the Arch, Debian, or RPM format package install.
- asciinema
- cmatrix
- figlet
- gdu
- gnupg
- imagemagick
- jq
- mplayer
- neofetch
- python3
- ranger
- speedtest-cli
- tmux
- w3m
After installing Asciiville the ascinit command performs a one-time initialization in which several additional packages are optionally installed. This post-installation configuration can install any or all of several terminal emulators along with character based tools. Terminal emulators supported by Asciiville available during post-install configuration are:
- kitty (the default and always installed if not already present)
- cool-retro-term (optionally installed if not present)
- gnome-terminal (optionally installed if not present)
- tilix (optionally installed if not present)
- xfce4-terminal (optionally installed if not present)
Tools installed during post-installation configuration include:
- asciimatics
- got
- gum
- vhs
- jrnl
- mutt
- neomutt
- neovim
- pipx
- rainbowstream
- tdraw
Installation
See the Install section for details on installing Asciiville.Configuration
See the Configuration section for details on configuring Asciiville and its components.Documentation
See the Documentation section for detailed documentation and usage of Asciiville and its components.Adding an ASCII Art Gallery
Additional info on adding and viewing ASCII art galleries in Asciiville can be found in the Adding Art Galleries article.
Asciiville includes several ASCII Art galleries produced by the renowned Ascii Artist, Doctorwhen. These galleries can be viewed by opening asciiville in interactive menu mode (execute asciiville with no arguments or the -i argument). From the main Asciiville menu select Ascii Art then select an Ascii Art slideshow to view from the list of slideshows available in the Asciiville Art menu.
Additional ASCII Art galleries can be added to the Asciiville Art menu by creating and populating a directory in /usr/share/asciiville/art/ with ASCII Art files. The convention in Asciiville is for ASCII Art filenames to end with the suffix .asc so generate or locate ASCII Art files, make sure the filenames end in .asc, and copy them to a new folder in /usr/share/asciiville/art/. The new ASCII Art gallery will show up in the menu listing the available ASCII Art slideshows the next time you run asciiville.
Generating ASCII Art
Asciiville provides utilities and convenience menus for generating ASCII Art from existing images. The pre-existing images can be in any image format. To generate ASCII Art from a folder of images either use the show_ascii_art command or the interactive menu interface in asciiville:
Using show_ascii_art to generate ASCII Art
The show_ascii_art command can be used to generate ASCII Art by supplying it with an input folder of existing images and a desired output folder to hold the generated ASCII Art files. To do so, invoke the command as follows:
show_ascii_art -I <input folder> -O <output folder>
For example, the command show_ascii_art -I /u/pics/beach -O /u/pics/asciibeach would convert all of the image files in the /u/pics/beach folder into ASCII Art files and store them in the /u/pics/asciibeach folder.
Note that the quality of generated ASCII Art is quite sensitive to the font in use. The best quality can be achieved with a fixed width font and small font size. You can think of the font as your paint brush and its size as the size of the brush. Higher resolution ASCII Art is achieved with a finer brush. The “palette” used to create ASCII Art is a string of characters. A default palette is defined in Asciiville but alternate palettes can be selected with command line switches.
If one of the terminal emulators that Asciiville is familiar with is used, the font and font size are set for you in a terminal profile or by command line arguments. The terminal emulators that Asciiville has integrated into its generation and viewing facilities are kitty, gnome-terminal, tilix, and xfce4-terminal. The currnt terminal window or console screen can also be used but in that case the font and font size will be whatever is already set.
If you use the current terminal window to generate/view ASCII Art then you may wish to set the font to a fixed width font and size 10 or 12. On the other hand, sometimes lower resolution ASCII Art is appealing. It’s up to you.
Using asciiville menus to generate ASCII Art
When the asciiville command is invoked in interactive menu mode the main menu contains an entry Generate ASCII Art. Selecting this menu entry will prompt the user to select an image input directory. Answering ‘y’ to the input directory prompt executed the Ranger file manager in directory selection mode. Use the arrow keys to browse folders, press Enter to enter a directory, and create a new directory with :mkdir <dirname>. While in the directory you wish to select, quit Ranger with ‘q’ and that directory will be selected as the image input directory. Do the same to select an ascii output directory.
After selecting an image input directory and ascii art output directory the user will then be prompted to confirm the directory selections and generate ASCII Art. Answering ‘y’ at this prompt will generate ASCII Art files for each of the images in the image input directory and store them in the ascii art output directory.
After using either of these methods to generate ASCII Art, follow the guide above to add the newly generated ASCII Art folder to the Asciiville ASCII Art galleries.
Adding and Viewing Art Galleries
The Asciiville article Adding and Viewing Art Galleries provides a brief tutorial introduction to generating a new ASCII Art gallery, customizing, and viewing it.
Asciiville default galleries can be viewed using the interactive menus in the asciiville command. Select the Ascii Art entry from the main menu, select the options you prefer (e.g. preferred terminal emulator and audio), and select the ascii art gallery you wish to view.
Note that the cool-retro-term terminal emulator will not, by default, display the full height of the ascii art included in Asciiville as the font size is too large. To view Asciiville Ascii Art slideshows using cool-retro-term, first reduce the font scaling in the settings menu to about 0.5. All the other terminal emulators supported by default in Asciiville (kitty, gnome-terminal, tilix, and xfce4-terminal) are dynamically configured during slideshow presentations to scale font sizes so ascii art is displayed correctly.
Asciiville ascii art viewing utilities including slideshow display utilize intelligent and configurable font size changes to render ascii art in higher quality. Each Asciiville ascii art gallery can be configured with options to control some of these font size and display features. To configure a gallery, add or edit the file /usr/share/asciiville/art/<gallery>/.config. An example Asciiville gallery configuration file can be found in /usr/share/asciiville/art/Vintage/.config:
scale_art_font=2
scale_txt_font=1
set_font_size=1
uses_ansi_escape=
show_filename= In this example, scale_art_font=2 indicates double the font size used for ascii art display; scale_txt_font=1 indicates no change to the text font size used for ascii art text display; set_font_size=1 indicates make font size changes; uses_ansi_escape= indicates this gallery’s ascii art does not utilize ANSI escape sequences to color its text; and show_filename= indicates do not display the ascii art filename.
The default settings for Asciiville ascii art galleries is:
scale_art_font=1
scale_txt_font=1
set_font_size=1
uses_ansi_escape=1
show_filename= To display a gallery’s ascii art filename below the ascii art displayed, set show_filename=1 in the gallery’s .config. Any, none, or all settings may be present in a gallery’s .config. If a setting is not present, Asciiville uses the defaults described above.
ASCII Art Tools
The Asciiville article ASCII Art Tools describes several tools not included in Asciiville that may be of use in drawing and painting ASCII Art.
ASCII Art Online
There are many online galleries of ASCII Art. In addition to the newly minted extended ASCII Art galleries included in Asciiville, the Asciiville project also includes a rich set of vintage ASCII Art in the Vintage art gallery. The citizens of Asciiville have been diligent in their efforts to comply with the artists’ licensing restrictions and only art that is freely redistributable is contained in Asciiville. Many of the online ASCII Art galleries available to the public are not as scrupulous with regards licensing requirements. In their defense, it can be extremely difficult to discover the origin and history of many of these works of art. Most were just culled from other archives who culled them from downloads of archives of defunct online bulletin boards and newsgroups and websites.
The point being, we here in Asciiville cannot guarantee anything about the legal provinance of online ASCII Art galleries. We can only assure you that the art included in Asciiville has been vetted and complies with all licensing requirements. Note that much of the art included in Asciiville prohibits redistribution for commercial purposes (e.g. the art in the Vintage gallery). Others prohibit the use of hate speech in conjunction with the display of the artist’s work. All of these requirements must be satisfied by Asciiville users, both those of us here in Asciiville and those who download and install our project.
That being said, exploring the online ASCII Art galleries is fun and much of it can be legally downloaded, utilized however you want, and redistributed. To get started exploring the world of online ASCII Art, visit the following:
- Joan Stark’s incredible archived website
- Christopher Johnson’s ASCII Art Collection
- Dernières images d’art ascii
- Typo Gallery
- ASCII Art Archive
- Textart
- Windows 93 on the Web
Figlet fonts
Asciiville installs many new Figlet Fonts in addition to those installed by the pyfiglet Python package. These fonts are used by the asciimatics Python package. To view a complete list of the installed pyfiglet fonts, run the command pyfiglet -l. To see an example rendering of each of the installed pyfiglet fonts including those installed by Asciiville, run the command bash /usr/share/asciiville/tools/bin/show_figlet_fonts. There are many fonts so you may wish to redirect the output of the bash /usr/share/asciiville/tools/bin/show_figlet_fonts command for use with an editor or pager:
bash /usr/share/asciiville/tools/bin/show_figlet_fonts > figlet-fonts-examples.txt
less figlet-fonts-examples.txt For an example of how to use the Figlet Fonts in an asciimatics animation, see /usr/bin/asciiart.
Build
See the Build section for details on building the Asciiville project and packaging.Removal
On Arch based Linux systems where the Asciiville package was installed using the Asciiville Arch format package, remove the Asciiville package by executing the command:
sudo pacman -Rs asciivilleOn Debian based Linux systems where the Asciiville package was installed using the Asciiville Debian format package, remove the Asciiville package by executing the command:
sudo apt remove asciivilleor
sudo dpkg -r asciivilleOn RPM based Linux systems where the Asciiville package was installed using the Asciiville RPM format package, remove the Asciiville package by executing the command:
sudo dnf remove Asciivilleor
sudo yum remove AsciivilleThe Asciiville package can be removed by executing the “Uninstall” script in the Asciiville source directory:
git clone https://github.com/doctorfree/Asciiville
cd Asciiville
./Uninstall On systems for which the manual installation was performed using the Install-bin.sh script, remove Asciiville manually by downloading the Uninstall-bin.sh script and, as a user with sudo privilege, execute the commands:
chmod 755 Uninstall-bin.sh
sudo ./Uninstall-bin.sh
Note that manual removal of Asciiville using the Uninstall-bin.sh script will not remove any of the manually installed dependencies. Manual installation and removal of Asciiville is not as robust as packaged installation and removal. Hopefully additional platform packaging will be available in the future. If you would like to assist with this effort, see the ‘Contributing’ section below.
What is ASCII
ASCII is an abbreviation for “American Standard Code for Information Interchange”, a character encoding standard for electronic communication. ASCII codes represent text in computers, telecommunications equipment, and other devices. Most modern character-encoding schemes are based on ASCII, although they support many additional characters.
ASCII Code Chart
ASCII was developed from telegraph code. Its first commercial use was as a seven-bit teleprinter code promoted by Bell data services. Originally based on the English alphabet, ASCII encodes 128 specified characters into seven-bit integers as shown by the ASCII chart above. The first edition of the standard was published in 1963.
Extended ASCII (EASCII or high ASCII) character encodings are eight-bit or larger encodings that include the standard seven-bit ASCII characters, plus additional characters. There are many extended ASCII encodings.
The phrase “ANSI character set” has no well-defined meaning and in the context of ANSI Art typically refers to “Code page 437”, the character set of the original IBM PC. In Asciiville the phrase “ANSI Art” refers to ASCII Art that utilizes the extended ASCII character encoding with the ability to render colored text. The phrase “ASCII Art” encompasses all such character renderings, ASCII and extended ASCII. Whether it’s “Art” is left as an exercise for the viewer.
ASCII Art History
The Asciiville article ASCII Art History provides us with a brief history of the development of text based art over the millenia, concrete poetry to typewriter art to ASCII and ANSI art.
Typewriter art by Flora F.F. Stacey from 1898
Videos
See the Videos section for several entertaining and informative Asciiville videos.Screenshots
Waterfall as Ascii Art generated and rendered with Asciiville
Asciiville Main Menu
Asciiville Sub-Menus: Ascii Art, Asciimatics Animations, MusicPlayerPlus, and RoonCommandLine
Ascii System Monitor, Maps, and Weather
Contributing
There are a variety of ways to contribute to the Asciiville project. All forms of contribution are appreciated and valuable. Also, it’s fun to collaborate. Here are a few ways to contribute to the further improvement and evolution of Ascii Art, Animation, and Utilities:
Testing and Issue Reporting
Asciiville is fairly complex with many components, features, options, configurations, and use cases. Although currently only supported on Linux platforms, there are a plethora of Linux platforms on which Asciiville can be deployed. Testing all of the above is time consuming and tedious. If you have a Linux platform on which you can install Asciiville and you have the time and will to put it through its paces, then issue reports on problems you encounter would greatly help improve the robustness and quality of Asciiville. Open issue reports at https://github.com/doctorfree/Asciiville/issues
Sponsor Asciiville
Asciiville is completely free and open source software. All of the Asciiville components are freely licensed and may be copied, modified, and redistributed freely. Nobody gets paid, nobody is making any money, it’s a project fully motivated by curiousity and love of art. However, it does take some money to procure development and testing resources. Right now Asciiville needs a multi-boot test platform to extend support to a wider variety of Linux platforms and potentially Mac OS X.
If you have the means and you would like to sponsor Asciiville development, testing, platform support, and continued improvement then your monetary support could play a very critical role. A little bit goes a long way in Asciiville. For example, a bootable USB SSD device could serve as a means of porting and testing support for additional platforms. Or, a decent cup of coffee could be the difference between a bug filled release and a glorious artistic adventure.
Sponsor the Asciiville project at https://github.com/sponsors/doctorfree
Contribute to Development
If you have programming skills and find Ascii text based art, animation, and utilities to be an interesting area, you can contribute to Asciiville development through the standard Github “fork, clone, pull request” process. There are many guides to contributing to Github hosted open source projects on the Internet. A good one is available at https://www.dataschool.io/how-to-contribute-on-github/. Another short succinct guide is at https://gist.github.com/MarcDiethelm/7303312.
Once you have forked and cloned the Asciiville repository, it’s time to setup a development environment. Although many of Asciiville’s commands are Bash shell scripts, there are also text based applicatons and games written in C and C++ along with documentation in Markdown format, configuration files in a variety of formats, examples, screenshots, video demos, build scripts, packaging, and more.
The development environment consists of several packages needed to build, package, and test Asciiville components. These include:
coreutils, sed, git, build-essential, gcc, g++, make, uuid-dev, libboost-graph-dev, cmake, python3, jdk, flex, bison, libncurses5-dev, autotools-dev, libjpeg-dev, libpng-dev, libcurl4-gnutls-dev, libncurses5-dev, autoconf-archive, pkg-config
On Arch, Debian, and RPM based systems the Asciiville installation package can be created with the mkpkg script. This script invokes the build script for each of the projects included with Asciiville, populates a distribution tree, and calls the respective packaging utilities. Packages are saved in the ./releases/<version>/ folder. Once a package has been created it can be installed with the Install script.
It’s not necessary to have C/C++ expertise to contribute to Asciiville development. Many of the Asciiville commands are Bash scripts and require no compilaton. Script commands reside in the bin directory. To modify a shell script, install Asciiville and edit the bin/<script> you wish to improve. Simply copy the revised script to /usr/bin and test your changes. Modifying the configuration files is a little more tricky. Configuration files generally live in the conf directory but each has its own installation location and some are modified by the ascinit command during installation. If you are just modifying the shell scripts or configuration files then you don’t need to worry about the extensive list of dependencies listed above.
Feel free to email me at github@ronrecord.com with questions or comments.
