pictureascii 0.1.2

Convert images into plain or colored ASCII art in the terminal, text, and PNG formats.

Picture ASCII

English | 한국어 | 日本語 | 简体中文 | Español | Français

A Python program that converts images into ASCII characters.

• Plain ASCII text output
• Terminal output using the source image's RGB colors
• Plain or color PNG export
• Custom character palettes, cell sizes, backgrounds, and foreground colors
• Transparent backgrounds and configurable PNG dimensions

Samples

• Source image
• ASCII text (the aspect ratio may differ because of GitHub font rendering)
• Plain ASCII image
• Color ASCII image

Installation

Python 3.10 or later is required.

pip install pictureascii

This command will be available after the package is published to PyPI.

For local development, run this command from the project root:

python -m pip install -e .

Basic Usage

pascii picture.png

pascii is the short alias for pictureascii; both commands behave identically. The output is saved as picture.txt next to the source image. Change the output width with --width:

pascii picture.png --width 200

Color Output

Apply the source image's RGB colors to each character:

pictureascii picture.png --color
pictureascii picture.png --color --color-scale 0.8

Color terminal output works best in a terminal with 24-bit ANSI color support, such as Windows Terminal or PowerShell.

PNG Export

pictureascii picture.png --save-image
pictureascii picture.png --color --save-image

Generated files use these names:

picture.txt
picture_plain.png   # --save-image
picture_color.png   # --color --save-image

The TXT file contains plain ASCII characters without ANSI color codes.

Cell Size

The default size of one ASCII character cell in a PNG is 10x14px.

pictureascii picture.png --cell-width 8 --cell-height 12 --save-image

Unless explicit PNG dimensions are provided, the size is calculated as follows:

PNG width  = number of columns x cell width
PNG height = number of rows x cell height

Character Palette

Use --chars to define the characters used for brightness levels. The leftmost character represents dark areas and the rightmost character represents bright areas.

pictureascii picture.png --chars "@%#*+=-:. "

Keep the space at the end of the palette for a natural brightness transition.

Background And Foreground

Colors accept #RGB or #RRGGBB values.

pictureascii picture.png --background "#101820" --foreground "#F2AA4C" --save-image

--foreground controls text color for plain PNG output. With --color, each character uses the source image's RGB color.

Transparent Background

pictureascii picture.png --transparent --save-image
pictureascii picture.png --color --transparent --save-image

PNG Dimensions

Set the output PNG dimensions directly:

pictureascii picture.png --image-width 1200 --image-height 800 --save-image

• When both dimensions are set, the image is saved at that exact size.
• When only one dimension is set, the other is calculated from the source aspect ratio.
• When neither is set, the dimensions are calculated from the character count and cell size.

Complete Example

pictureascii picture.png --color --width 180 --chars "@%#*+=-:. " --cell-width 10 --cell-height 14 --image-width 1800 --transparent --save-image

Options

Option	Description	Default
image	Path to the source image	Required
-w, --width	Number of output columns	120
-o, --output	TXT output path	Source name with .txt
--ratio	Terminal character aspect-ratio correction	0.5
--invert, --no-invert	Invert character brightness	Enabled
--color	Apply source RGB colors to characters	Disabled
--color-scale	Color brightness multiplier	1.0
--save-image	Save the current output mode as PNG	Disabled
--image-font-size	Legacy PNG renderer font size	14
--cell-width	Character cell width	10
--cell-height	Character cell height	14
--chars	Character palette	Built-in palette
--background	PNG background color	Automatic
--foreground	Plain PNG text color	Automatic
--transparent	Use a transparent PNG background	Disabled
--image-width	PNG width	Automatic
--image-height	PNG height	Automatic

View the full command help:

pictureascii --help

You can also run the package as a module:

python -m pictureascii picture.png --color

Development And Release

Run the tests:

python -m unittest discover -s tests -v

Build and validate the distributions:

python -m pip install --upgrade build twine
python -m build
python -m twine check dist/*

Publish to TestPyPI first, then publish the verified release to PyPI:

python -m twine upload --repository testpypi dist/*
python -m twine upload dist/*

Before releasing a new version, update the version in both pyproject.toml and src/pictureascii/__init__.py, then rebuild dist.