Metadata-Version: 2.4
Name: asciinator
Version: 0.1.0
Summary: Convert images to ANSI-colored ASCII/Unicode art in the terminal
Author: Shannon Barber
Author-email: Shannon Barber <sgbarber@gmail.com>
License-Expression: MIT
License-File: LICENSE
Requires-Dist: pillow>=10.0
Requires-Dist: cairosvg>=2.5 ; extra == 'svg'
Requires-Python: >=3.10
Provides-Extra: svg
Description-Content-Type: text/markdown

# asciinator

Convert images to ANSI-colored ASCII/Unicode art in your terminal.

Supports three rendering modes:

- **`halfblock`** (default) — Unicode upper-half-block (`▀`) with 24-bit foreground *and* background color. Packs two image rows per terminal line, doubling vertical resolution.
- **`shade`** — Unicode shade blocks (`█▓▒░`) with 24-bit foreground color.
- **`ascii`** — Classic ASCII ramp (`@%#*+=-:.`) with 24-bit foreground color.

## Install

```sh
pip install asciinator
```

For SVG input support:

```sh
pip install 'asciinator[svg]'
```

Or with [uv](https://docs.astral.sh/uv/):

```sh
uv tool install asciinator
```

## Usage

```sh
asciinator path/to/image.png
asciinator logo.jpg --mode shade
asciinator photo.png --mode ascii --chars "@%#*+=-:." --width 120
asciinator icon.svg --saturation 1.4 -o icon.ansi
```

### Options

| Option | Description |
|---|---|
| `--mode {ascii,shade,halfblock}` | Output mode (default: `halfblock`) |
| `--chars CHARS` | Custom character ramp, darkest→brightest (ignored for `halfblock`) |
| `--width N` | Output width in characters (default: terminal width) |
| `--saturation F` | Color saturation multiplier (default: 1.0; >1 is more vivid) |
| `-o FILE`, `--output FILE` | Also write output (with ANSI codes) to this file |

Output is auto-sized to fit the terminal height. Your terminal must support 24-bit true color (most modern terminals do).

## Development

This project uses [uv](https://docs.astral.sh/uv/) for dependency management and builds.

```sh
# Run from source
uv run asciinator path/to/image.png

# Build wheel + sdist into dist/
uv build

# Install the built wheel for local smoke testing
uv tool install --from dist/asciinator-0.1.0-py3-none-any.whl asciinator
```

### Publishing

Build artifacts first:

```sh
uv build
```

Dry-run on TestPyPI:

```sh
# Create a token at https://test.pypi.org/manage/account/token/
uv publish --publish-url https://test.pypi.org/legacy/ \
           --token pypi-<TESTPYPI_TOKEN>

# Verify install from TestPyPI
uv tool install --index-url https://test.pypi.org/simple/ \
                --extra-index-url https://pypi.org/simple/ \
                asciinator
```

Publish to real PyPI:

```sh
# Create a token at https://pypi.org/manage/account/token/
uv publish --token pypi-<PYPI_TOKEN>
```

You can also set `UV_PUBLISH_TOKEN` in your environment instead of passing `--token`.

## License

MIT — see [LICENSE](LICENSE).
