|Feb 13, 2024
|Aug 24, 2023
|Jul 23, 2023
|Jun 20, 2023
|Mar 27, 2022
#59 in Command line utilities
409 downloads per month
Used in clp
Artem is a small cli program, written in rust, to easily convert images
to ascii art, named after the latin word for art. By default it tries to use truecolor, if the terminal does not support truecolor, it falls back to 16 Color ANSI. When the ascii image is written to a file, the image will not use colors.
.webp and many more.
If you want to use this project as a library, please refer to the docs.
Is this project still being maintained?
Yes. Although there is currently no active development of new features, issue and new feature request will still be worked on. If you have any issue or have an idea for a new feature, please create an issue.
For simply converting an image:
The input can either be one or multiple file paths or URLs.
NOTE: To use URLs, the
web_image feature has to be enabled. It is enabled by default.
For more options use:
To use custom ascii chars, use the
-c for short) argument.The characters should be ordered from darkest/densest to lightest.
If the background should be invisible, add a space at the end. Alternatively this program has already 3 predefined character sets,
accessibly by supplying the
--characters argument to gether with the number (
2) of the preset that should be used.
By default preset
1 is used.
artem PATH --characters "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789<>|,.-#+!$%&/()=?*'_:; "
To change the size at which the converted image is displayed, use:
#for auto sizing height
artem PATH --height
#for auto-sizing width
artem PATH --width
#for manual resizing use the --size flag
artem PATH --size 100
It is also possible to center the image using:
#center the image horizontally
artem PATH --centerX
#center the image vertically
artem PATH --centerY
To save the the image to a file, use the
artem PATH --output ascii.txt
#if the output file is an html file, the resulting ascii art will be saved as html ascii art, which supports colors
artem PATH --output ascii.html
# or alternatively, use an .asn file for colored ascii text
artem PATH --output ascii.ans
--outline flag, the given input image will be filtered, to only contain an outline, which will then be converted. Please be aware, that this will take some additional time, as well as that it might not perfectly work on every image. For the best result, please use an image with a clear distinction between the background and the foreground.
artem PATH --outline
For an even better result, it might be worthwhile trying out the
--hys flag, potentially with characters better suited for outlines, for example.
artem PATH --outline --hysteresis --characters "|/\_. "
All platforms (recommended)
The easiest way to install artem is using
cargo install artem
It will automatically add
artem to your PATH variable, so it can used like shown in the usage section.
cargo is not installed, visit the cargo book for installation instructions.
Debian-based Distributions (e.g. Ubuntu)
For Debian-based Distributions, like Ubuntu, download the
.deb file from the release page and install it with:
sudo dpkg -i artem.deb
.deb package also contains tab completions (for bash, zsh and fish) and a man page.
artem is available as an AUR package. You can install it with your favorite aur-helper, for example with
yay -S artem
This will build it from source.
Alternatively, it is also available as a precompiled binary (
yay -S artem-bin
On other distributions use the binary file provided in the release tab.
brew is installed, you can also use
brew to install it. See the MacOS Homebrew section for more information.
Warning It's no longer recommended to install
artemvia Homebrew, as the tap is no longer maintained due to difficulty working with Homebrew. If you wish to maintain the tap, please contact me.
brew install finefindus/tap/artem
The homebrew version has the added benefit of also installing the man page and tab completions for bash, zsh and fish.
To install the windows version, without using
cargo, download either the gnu- or the mscv compiled
.zip files from release tab and extract the
.exe. It should be noted that you will have to add the
.exe manually to the PATH variable.
artem has shell completions and a man page available. When using the homebrew version, the
.deb package, or the aur versions, they are installed automatically, whilst for using the binary files with shell completions, the completion files, which be can be found in the compressed release file, have to be copied to the correct locations.
Assuming the compressed file has been uncompressed, use following commands to copy the files to their correct location for unix-like systems:
Shell Completions and Man page
#copy the bash completion file
sudo cp completions/artem.bash /etc/bash_completion.d/
For zsh add the file to a
#copy the zsh completion file
cp completions/_artem $fpath
For fish add the file to the fish completions directory:
#copy the fish completion file
cp completions/artem.fish $HOME/.config/fish/completions/
For Windows add
. /path/to/_artem.ps1 (including the dot) to the PowerShell profile.
artem also provides a man page for the binary releases contained in the
doc directory. To view it using the
-l flag for
man to view a local file.
#view the local man page
man -l doc/artem.1
Building from source
Assuming you have rust/cargo installed, you can build the project with:
cargo build --release
--release flag disables debugging options, increasing performance.
Visit the rust homepage for installation instructions if rust is not installed.
This disables the default features, whilst enabling all other specified features:
cargo build --release --no-default-features --features FEATURES
For more information about the usage of features, please refer to the cargo book.
The following features are currently available:
web_imageAccept Image URLs as input (enabled by default)
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change. Please be aware that it might take some time for someone to respond.
Also a big thanks to ripgrep for indirectly helping with inspiration for the build setup.
The following images are used for testing/examples:
Better average the RGB values of multiple pixel
Use the current terminal size to auto fit the image
Support ANSI terminal colors
Convert output to colored html
Add even more test
Convert multiple files at once
Automate copying of completion files from OUT_DIR to deployment/assets
Use edge detection and directional ascii
Implement better resizing