Metadata-Version: 2.4
Name: pictureascii
Version: 0.1.2
Summary: Convert images into plain or colored ASCII art in the terminal, text, and PNG formats.
Keywords: ascii,ascii-art,image,terminal,cli
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Graphics :: Graphics Conversion
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: Pillow>=9.1
Dynamic: license-file

# Picture ASCII

**English** | [한국어](i18n/README.ko.md) | [日本語](i18n/README.ja.md) | [简体中文](i18n/README.zh-CN.md) | [Español](i18n/README.es.md) | [Français](i18n/README.fr.md)

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](https://github.com/doyeon789/pictureascii/tree/main/example/images/sample.png)
- [ASCII text (the aspect ratio may differ because of GitHub font rendering)](https://github.com/doyeon789/pictureascii/tree/main/example/outputs/sample.txt)
- [Plain ASCII image](https://github.com/doyeon789/pictureascii/tree/main/example/outputs/sample_plain.png)
- [Color ASCII image](https://github.com/doyeon789/pictureascii/tree/main/example/outputs/sample_color.png)

## Installation

Python 3.10 or later is required.

```bash
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:

```bash
python -m pip install -e .
```

## Basic Usage

```bash
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`:

```bash
pascii picture.png --width 200
```

## Color Output

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

```bash
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

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

Generated files use these names:

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

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

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

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

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

```bash
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

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

## PNG Dimensions

Set the output PNG dimensions directly:

```bash
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

```bash
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:

```bash
pictureascii --help
```

You can also run the package as a module:

```bash
python -m pictureascii picture.png --color
```

## Development And Release

Run the tests:

```bash
python -m unittest discover -s tests -v
```

Build and validate the distributions:

```bash
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:

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