Metadata-Version: 2.4
Name: asciify-image
Version: 0.1.0
Summary: Convert images to ASCII art with color, dithering, and multiple character sets
Project-URL: Homepage, https://github.com/visakhunnikrishnan/asciify
Project-URL: Repository, https://github.com/visakhunnikrishnan/asciify
Project-URL: Issues, https://github.com/visakhunnikrishnan/asciify/issues
Author-email: Visakh Unni <contact@visakhunni.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ascii,ascii-art,cli,converter,image,terminal
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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 :: Artistic Software
Classifier: Topic :: Multimedia :: Graphics :: Graphics Conversion
Classifier: Topic :: Terminals
Requires-Python: >=3.9
Requires-Dist: numpy>=1.20.0
Requires-Dist: pillow>=9.0.0
Provides-Extra: dev
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# Asciify

[![PyPI version](https://badge.fury.io/py/asciify-image.svg)](https://badge.fury.io/py/asciify-image)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A command-line tool and Python library that converts images into high-quality ASCII art with optional color, dithering, and brightness/contrast controls.

## Features

- **Multiple Character Sets**: Choose from simple, complex, braille blocks, or Unicode block elements
- **Color Output**: Full ANSI 256-color support for colored ASCII art
- **Floyd-Steinberg Dithering**: Optional dithering for improved detail representation
- **Image Adjustments**: Control brightness and contrast
- **Flexible Sizing**: Auto-fit to terminal width or specify custom dimensions
- **Invert Mode**: Swap light and dark for different backgrounds

## Installation

### From PyPI

```bash
pip install asciify-image
```

### From Source

```bash
git clone https://github.com/visakhunnikrishnan/asciify.git
cd asciify
pip install -e .
```

## Usage

### Command Line

```bash
# Basic usage
asciify image.jpg

# Specify width
asciify image.jpg -W 80

# Use complex character set with color
asciify image.jpg -c complex --color

# Enable dithering with custom brightness
asciify image.jpg --dither -b 1.2

# Save output to file
asciify image.jpg -o output.txt

# High contrast black and white
asciify photo.png --contrast 1.5 --invert

# Braille art (requires Unicode-capable terminal)
asciify image.png -c blocks
```

### Python Library

```python
from asciify import ASCIIArtConverter

# Basic conversion
converter = ASCIIArtConverter()
ascii_art = converter.convert("image.jpg", width=80)
print(ascii_art)

# With options
converter = ASCIIArtConverter(
    charset="complex",
    colored=True,
    dither=True,
)
ascii_art = converter.convert(
    "image.jpg",
    width=100,
    brightness=1.2,
    contrast=1.1,
    invert=False,
)

# Convert PIL Image directly
from PIL import Image

img = Image.open("photo.png")
ascii_art = converter.convert_image(img, width=80)
```

## Options

| Option | Description |
|--------|-------------|
| `-W, --width` | Output width in characters |
| `-H, --height` | Output height in characters |
| `-c, --charset` | Character set: `simple`, `complex`, `blocks`, `symbols` |
| `--color` | Enable colored output |
| `--dither` | Enable Floyd-Steinberg dithering |
| `--invert` | Invert the image colors |
| `-b, --brightness` | Brightness adjustment (0.0-2.0, default: 1.0) |
| `--contrast` | Contrast adjustment (0.0-2.0, default: 1.0) |
| `-o, --output` | Save output to file |

## Character Sets

- **simple**: ` .:-=+*#%@` - Basic ASCII characters
- **complex**: ` .",:;!~+-xmo*#W&8@` - Extended ASCII for more detail
- **blocks**: Braille patterns for high-density output
- **symbols**: Unicode block elements for solid fills

## Development

### Setup

```bash
git clone https://github.com/visakhunnikrishnan/asciify.git
cd asciify
pip install -e ".[dev]"
```

### Running Tests

```bash
pytest
```

### Code Quality

```bash
ruff check src tests
mypy src
```

## Requirements

- Python 3.9+
- Pillow
- NumPy

## License

MIT License - see [LICENSE](LICENSE) for details.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
