Skip to content

Picharsso#

Picharsso

A utility for converting images to text art.

Installation#

Run the following command:

pip install picharsso

This will:

  • download and install the picharsso Python package (along with its dependencies).
  • create an executable, picharsso, for the CLI (command line interface).
Verification

To verify that Picharsso is installed, run:

python -c "import picharsso"

Commands (CLI)#

Picharsso ships with a CLI that provides some basic functionality from the terminal.

Usage

Run the following command to display a helpful message:

picharsso -h

Usage: picharsso [options] <command> [args]

  A utility for converting images to text art.

Options:
  -h, --help  Show this message and exit.

Commands:
  draw  Generate text art from an image.
  info  Displays package information.

Consider the following image:

Apple logo

Apple Computer [Rob Janoff, 1977]

To convert an image to text art, run:

picharsso draw -c -H 32 <path/to/image> braille

Here's what it should look like:

Apple logo in text (Braille style)

Breakdown

Argument Effect
-c Apply image colors to the output text.
-H 32 Sets the number of lines of the output text to 32.
braille Use the Braille style. 
picharsso draw -c -H 32 <path/to/image> gradient

Here's what it should look like:

Apple logo in text (gradient style)

Breakdown

Argument Effect
-c Apply image colors to the output text.
-H 32 Sets the number of lines of the output text to 32.
gradient Use the gradient style.

Warning

Don't forget to replace <path/to/image>.

CLI

Refer to the CLI documentation to learn about the various commands and arguments.

Library (API)#

The example from the previous section can be implemented in just a few lines of Python:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
from PIL import Image
from picharsso import new_drawer

if __name__ == "__main__":
    # Open image
    image = Image.open("<path/to/image>")

    # Define drawer
    drawer = new_drawer("braille", height=32, colorize=True)

    # Print drawer output
    print(drawer(image))

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
from PIL import Image
from picharsso import new_drawer

if __name__ == "__main__":
    # Open image
    image = Image.open("<path/to/image>")

    # Define drawer
    drawer = new_drawer("gradient", height=32, colorize=True)

    # Print drawer output
    print(drawer(image))

Pillow

Picharsso integrates well with Pillow, the friendly PIL fork.

Styles

Refer to the Styles documentation for an in-depth guide to the image processing behind Picharsso.

Now consider this animated GIF:

Nyan Cat

Nyan Cat

With some more lines of code, you can animate GIFs in text!

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
import time

from PIL import Image
from picharsso import new_drawer
from picharsso.utils import clear_screen, terminal_size


if __name__ == "__main__":
    # Open image
    image = Image.open("<path/to/image>")

    # Get terminal height
    height, _ = terminal_size()

    # Define drawer
    drawer = new_drawer("braille", height=height, colorize=True, threshold=0)

    # Iterate over frames
    texts = []
    for frame_id in range(image.n_frames):
        # Select frame
        image.seek(frame_id)

        # Save output for frame
        texts.append(drawer(image))

    # Iterate over saved outputs in a circular manner
    num_frames = len(texts)
    counter = 0
    while True:
        # Refresh
        clear_screen()

        # Print output
        print(texts[counter])

        # Set a delay between frames
        time.sleep(1 / num_frames)

        # Circular increment
        counter = (counter + 1) % num_frames

Here's what it should look like:

Nyan Cat in text (Braille style) 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
import time

from PIL import Image
from picharsso import new_drawer
from picharsso.utils import clear_screen, terminal_size


if __name__ == "__main__":
    # Open image
    image = Image.open("<path/to/image>")

    # Get terminal height
    height, _ = terminal_size()

    # Define drawer
    drawer = new_drawer("gradient", height=height, colorize=True)

    # Iterate over frames
    texts = []
    for frame_id in range(image.n_frames):
        # Select frame
        image.seek(frame_id)

        # Save output for frame
        texts.append(drawer(image))

    # Iterate over saved outputs in a circular manner
    num_frames = len(texts)
    counter = 0
    while True:
        # Refresh
        clear_screen()

        # Print output
        print(texts[counter])

        # Set a delay between frames
        time.sleep(1 / num_frames)

        # Circular increment
        counter = (counter + 1) % num_frames

Here's what it should look like:

Nyan Cat in text (gradient style)

API

Refer to the API documentation to learn about the various classes and functions.

Examples

Check out some more examples.

You can use an image directly from the web too!