---
name: ascii-image-converter
description: Convert images (PNG, JPEG, GIF, WEBP) to ASCII art using Python PIL/Pillow. Supports customizable character sets and output dimensions.
version: 1.0.0
author: Hermes Agent
license: MIT
dependencies:
  - Pillow
metadata:
  hermes:
    tags: [ASCII, Art, Image, Conversion, PIL, Pillow, Text-Art]
    related_skills: [ascii-art]

---

# ASCII Image Converter Skill

Convert any image file to ASCII art using Python PIL/Pillow library. This skill provides finer control than CLI tools and works in environments where ascii-image-converter or jp2a are not available.

## Setup

```bash
# Install Pillow (usually already installed)
pip install Pillow --break-system-packages

# Or if using Hermes venv:
source /root/.hermes/hermes-agent/venv/bin/activate
pip install Pillow
```

## Usage

### Basic Conversion

```python
from PIL import Image

# ASCII character set (dark to light)
ASCII_CHARS = "@%#*+=-:. "

def image_to_ascii(image_path, width=100):
    image = Image.open(image_path)
    
    # Calculate aspect ratio (characters are taller than wide)
    aspect_ratio = image.height / image.width
    new_height = int(aspect_ratio * width * 0.55)
    image = image.resize((width, new_height))
    
    # Convert to grayscale
    image = image.convert("L")
    
    # Map pixels to ASCII characters
    pixels = list(image.getdata())
    ascii_str = ""
    for pixel in pixels:
        ascii_str += ASCII_CHARS[pixel // 32]
    
    # Split into lines
    ascii_image = ""
    for i in range(0, len(ascii_str), width):
        ascii_image += ascii_str[i:i+width] + "\n"
    
    return ascii_image

# Usage
result = image_to_ascii("/path/to/image.jpg", width=120)
print(result)

# Save to file
with open("/path/to/output.txt", "w") as f:
    f.write(result)
```

### Custom Character Sets

| Style | Character Set | Best For |
|-------|---------------|----------|
| Standard | `@%#*+=-:. ` | General purpose |
| Detailed | `$@B%8&WM#*oahkbdpqwmZO0QLCJUYXzcvunxrjft/\|()1{}[]?-_+~<>i!lI;:,"^`'. ` | High detail images |
| Simple | `█▓▒░ ` | Block characters |
| Binary | `10 ` | Binary/digital art |
| Minimal | `#- ` | Simple contrast |

### Advanced Options

```python
# Invert colors (for dark backgrounds)
ASCII_CHARS = " .:-=+*#%@"

# Adjust contrast by changing bucket size
# Smaller buckets = more contrast
bucket_size = 16  # Instead of default 32 (256/8)
ascii_str += ASCII_CHARS[pixel // bucket_size]

# Custom width for different output contexts
width=80    # Terminal-safe
width=100   # Standard
width=150   # Wide format
width=200   # High detail
```

## Output Format

The skill outputs plain text ASCII art that can be:
- Displayed directly in terminal
- Saved to `.txt` files
- Embedded in markdown code blocks
- Sent as message attachments

## File Delivery

After conversion, deliver the file using:

```python
# Save file
with open("/root/.hermes/workspace/output.txt", "w") as f:
    f.write(result)

# Then send to user
MEDIA:/root/.hermes/workspace/output.txt
```

## Tips

1. **Width selection**: 80-120 characters works best for most terminals
2. **Aspect ratio**: Multiply by 0.55 to compensate for character height/width ratio
3. **File size**: Large images should be resized to avoid excessive output
4. **Contrast**: Images with good contrast produce better ASCII art
5. **Saving**: Always save to file for user download, not just display

## Error Handling

```python
try:
    image = Image.open(image_path)
except Exception as e:
    return f"无法打开图片：{e}"
```

## Related Skills

- `ascii-art`: Text-based ASCII art generation
- `excalidraw`: Diagram creation