Skip to main content

A utility for converting images to text art.

Project description

Picharsso


A utility for converting images to text art.
PyPI - Status pypi package GitHub

Installation    |    Documentation    |    Examples    |    Contributing

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

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> 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.

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

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

Library

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

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))

Here's what it should look like:

Apple logo in text (Braille style)

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!

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)

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!

Contributing

Do you have a feature request, bug report, or patch? Great! Check out the contributing guidelines!

License

Copyright (c) 2019 Kelvin DeCosta. Released under the MIT License. See LICENSE for details.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for picharsso, version 2.0.1
Filename, size File type Python version Upload date Hashes
Filename, size picharsso-2.0.1-py3-none-any.whl (19.1 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size picharsso-2.0.1.tar.gz (13.0 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page