https://github.com/cpscript/art
Print any image into your termianl with this; High-fidelity image-to-ASCII transformation with advanced rendering capabilities for any image type cli framework.
https://github.com/cpscript/art
ansi api ascii ascii-art cli command-line python text time-to-text
Last synced: 4 months ago
JSON representation
Print any image into your termianl with this; High-fidelity image-to-ASCII transformation with advanced rendering capabilities for any image type cli framework.
- Host: GitHub
- URL: https://github.com/cpscript/art
- Owner: CPScript
- License: mit
- Created: 2025-05-02T05:31:50.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2025-05-05T15:44:59.000Z (8 months ago)
- Last Synced: 2025-08-30T05:57:43.106Z (4 months ago)
- Topics: ansi, api, ascii, ascii-art, cli, command-line, python, text, time-to-text
- Language: Python
- Homepage:
- Size: 217 KB
- Stars: 5
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# ART: ASCII Rendering Toolkit
## Enterprise Architecture Overview
"ART" implements a framework for high-fidelity image-to-ASCII transformation with advanced rendering capabilities. This toolkit provides terminal graphics rendering with fine-grained parameter control, extensive customization options, and optimized I/O handling for integration into complex processing pipelines.
### Core Technology Stack
- High-performance image processing subsystem
- Advanced Unicode character mapping engine
- ANSI color implementation architecture
- Terminal-aware adaptive rendering
- Stream-optimized I/O protocol
## Installation Protocol
### Development Implementation (recomended)
```bash
git clone https://github.com/CPScript/ART
cd ART/art
pip install -e .
```
## Feature Implementation Matrix
- **Dynamic Symbol Mapping**: Configurable character sets for precision intensity mapping
- **Color Preservation Technology**: ANSI color sequence generation with 16.7M color depth
- **Dimension Control Protocol**: Multiple scaling strategies with terminal-aware rendering
- **Format Transcoding Engine**: Support for all standard image formats via Pillow integration
- **I/O Streaming Architecture**: UNIX-compatible filtering with stdin/stdout capabilities
- **Background Control System**: Custom background color specification with RGB precision
## Quick Implementation Reference
```bash
# Basic implementation with default parameters
art image.jpg
# Enhanced rendering with color preservation
art image.jpg -u
# Enterprise-grade rendering with optimized parameters
art image.jpg -c " .:-=+*#%@" -s 2 -w 80 -H 40 -u -r -b "40,40,40" --filter lanczos
```
## Command-Line Protocol Specification
The ART command-line interface implements a comprehensive parameter architecture for maximum rendering control:
```
ART [OPTIONS] [IMAGE_PATH]
```
### Positional Parameters
| Parameter | Description | Implementation Notes |
|-----------|-------------|---------------------|
| `IMAGE_PATH` | Source image for transformation | Optional; Reads from STDIN if omitted |
### Option Implementation Specification
| Short Form | Long Form | Type | Default | Description |
|------------|-----------|------|---------|-------------|
| `-c` | `--symbols` | String | `" .,-~!;:=*&%$@#"` | Character intensity mapping set (lightest to darkest) |
| `-s` | `--scale` | Integer | `4` | Image dimension reduction factor (higher values = smaller output) |
| `-w` | `--width` | Integer | Source-dependent | Explicit output width specification (columns) |
| `-H` | `--height` | Integer | Source-dependent | Explicit output height specification (rows) |
| `-b` | `--background` | String | None | Background color implementation (`r,g,b` or `#RRGGBB` format) |
| `-r` | `--reverse` | Flag | `false` | Foreground/background color inversion |
| `-u` | `--color` | Flag | `false` | ANSI color mode activation |
| N/A | `--filter` | String | `nearest` | Resampling algorithm selection (`nearest`, `bilinear`, `bicubic`, `lanczos`) |
| `-v` | `--version` | Flag | N/A | Version identification |
| N/A | `--help` | Flag | N/A | Command documentation display |
### Complex Parameter Implementation Patterns
#### Symbol Set Architecture (`-c`, `--symbols`)
The symbol set determines the character-to-intensity mapping protocol:
```bash
# Binary implementation (high contrast)
art image.jpg -c " #"
# Grayscale implementation (standard density)
art image.jpg -c " .:-=+*#%@"
# Extended implementation (maximum fidelity)
art image.jpg -c " .'`^\",:;Il!i><~+_-?][}{1)(|/tfjrxnuvczXYUJCLQ0OZmwqpdbkhao*#MW&8%B@$"
```
#### Dimension Control Architecture
ART implements multiple strategies for dimension management:
```bash
# Scale-based implementation (factor of 2 reduction)
art image.jpg -s 2
# Width-constrained implementation (height auto-scaled)
art image.jpg -w 80
# Fixed-dimension implementation
art image.jpg -w 120 -H 60
# Terminal-optimized implementation
art image.jpg -w $(tput cols) -H $(( $(tput lines) - 2 ))
```
#### Color Management Architecture
```bash
# Standard color implementation
art image.jpg -u
# Background color implementation
art image.jpg -u -b "255,200,180"
# Color plane inversion implementation
art image.jpg -u -r
# Complete color control implementation
art image.jpg -u -r -b "#E0E0FF"
```
#### Resampling Architecture Selection
```bash
# Performance-optimized implementation
art image.jpg --filter nearest
# Quality-optimized implementation
art image.jpg --filter lanczos
```
# Enterprise-Level Implementation Guide: Solid Block Character Rendering in ART
## Technical Implementation Architecture
To implement solid square/block character rendering in ART, you need to leverage the symbol set customization capabilities via the `-c/--symbols` parameter. This parameter accepts a string of characters that will be mapped to pixel intensity values during the ASCII transformation process.
## Block Character Implementation Specification
The Unicode specification provides several block characters designed specifically for terminal graphics rendering:
| Unicode | Character | Description | Density |
|---------|-----------|-------------|---------|
| U+2588 | █ | FULL BLOCK | 100% |
| U+2593 | ▓ | DARK SHADE | 75% |
| U+2592 | ▒ | MEDIUM SHADE | 50% |
| U+2591 | ░ | LIGHT SHADE | 25% |
| U+0020 | ` ` | SPACE | 0% |
## Core Implementation Patterns
### 1. Single Block Implementation (Binary Representation)
To render the image using only full blocks (filled squares):
```bash
art image.jpg -c "█"
```
This creates a high-contrast rendering where every character is a solid block, with color preservation if the `-u` flag is enabled.
### 2. Gradient Block Implementation (Density-Based)
For a grayscale-like effect using block density:
```bash
art image.jpg -c " ░▒▓█"
```
This implementation maps pixel intensity to progressively denser block characters, creating a gradient effect with five distinct levels.
### 3. Solid Block with Color Implementation (Maximum Fidelity)
```bash
art image.jpg -c "█" -u
```
This enterprise-grade implementation combines solid block characters with ANSI color preservation, creating a pixel-perfect terminal rendering at the character cell resolution.
## Advanced Implementation Strategies
### 1. Inverted Block Rendering
```bash
art image.jpg -c "█" -u -r -b "0,0,0"
```
This implementation renders solid blocks with inverted color planes against a black background, maximizing contrast and visibility.
### 2. Terminal-Optimized Block Rendering
```bash
art image.jpg -c "█" -u -w $(tput cols) -H $(( $(tput lines) - 2 ))
```
This implementation dynamically adapts the block rendering to the current terminal dimensions, ensuring optimal display characteristics.
### 3. Half-Block Implementation (Enhanced Resolution)
For terminals supporting Unicode, you can leverage half-block characters to effectively double the vertical resolution:
```bash
art image.jpg -c "▀▄█" -u -s 2
```
This advanced implementation uses upper half-block (▀), lower half-block (▄), and full block (█) characters to create higher-resolution renderings within terminal constraints.
## Performance Considerations
The solid block implementation pattern offers several performance advantages:
1. **Rendering Efficiency**: Simpler character set reduces ASCII art generation computational overhead
2. **Memory Optimization**: Single-character representation minimizes buffer size requirements
3. **Display Optimization**: Block characters optimize terminal rendering capabilities
4. **Bandwidth Conservation**: Reduced character set variety improves compression ratios for transmission
## Implementation Examples
### Standard Solid Block Implementation
```bash
# Basic solid block rendering
art photo.jpg -c "█"
# Color-preserving solid block rendering
art photo.jpg -c "█" -u
# Gradient block rendering with color
art photo.jpg -c " ░▒▓█" -u
```
### Enterprise-Grade Block Rendering
```bash
# Maximum-resolution block rendering with color preservation
art high_res_image.jpg -c "█" -u -s 1 --filter lanczos
# Memory-optimized block rendering
art large_image.jpg -c "█" -u -s 6 --filter nearest
```
This comprehensive implementation guide provides the technical foundation for leveraging solid block characters in ART, enabling pixel-accurate terminal graphics rendering with optimal performance characteristics.
## Programmatic Implementation Architecture
ART can be integrated into advanced processing pipelines via its Python API:
```python
from PIL import Image
from art import Config, Symbols, COLORS, REVERSE, convert_image_to_ascii
import sys
config = Config(
symbols=Symbols(list(" .:-=+*#%@")),
flags=COLORS | REVERSE,
background=ANSIColor(40, 40, 40)
)
image = Image.open("image.jpg")
convert_image_to_ascii(config, image, sys.stdout)
```
### Advanced In-Memory Text Representation
For sophisticated integration scenarios:
```python
from PIL import Image
from art import Config, Symbols, COLORS, TextImage, convert_image_to_ascii
config = Config(symbols=Symbols(list(" .:-=+*#%@")), flags=COLORS)
image = Image.open("image.jpg")
width, height = image.size
text_image = TextImage(config, width, height)
convert_image_to_ascii(config, image, text_image)
print(text_image)
```
## Pipeline Integration Architecture
### Stream Processing Implementation
```bash
cat image.jpg | art -u > output.txt
convert image.jpg -resize 50% -colorspace gray jpg:- | art -c " .:-=+*#%@" > output.txt
```
### Batch Processing Protocol
```bash
for img in *.jpg; do
output_file="${img%.jpg}.txt"
art "$img" -u -s 4 > "$output_file"
done
```
## Performance Optimization Matrix
| Use Case | Command Implementation | Memory Complexity | Processing Efficiency |
|----------|------------------------|-------------------|------------------------|
| Maximum Quality | `-s 1 -u --filter lanczos` | O(wh) | O(wh log wh) |
| Standard Display | `-s 4 -u` | O(wh/16) | O(wh/16) |
| Memory Optimization | `-s 8 -c " #" --filter nearest` | O(wh/64) | O(wh/64) |
| Color Preservation | `-u -c "█"` | O(wh) | O(wh) |
## System Requirements Specification
- Python 3.7 or higher
- Pillow 9.0.0 or higher
- ANSI-compatible terminal for color rendering
- Unicode support for block character rendering
## Development Protocol
### Environment Configuration
```bash
git clone https://github.com/CPScript/ART.git
cd ART
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
pip install -e ".[dev]"
```
## Acknowledgments
- Pillow project for image processing capabilities
- Unicode Consortium for terminal graphics character specifications
- ANSI Terminal Standard for color rendering protocol
---
Made with precision engineering for terminal graphics excellence