{"id":30770662,"url":"https://github.com/cpscript/art","last_synced_at":"2025-09-04T23:12:07.191Z","repository":{"id":291493900,"uuid":"976438158","full_name":"CPScript/ART","owner":"CPScript","description":"Print any image into your termianl with this; High-fidelity image-to-ASCII transformation with advanced rendering capabilities for any image type cli framework.","archived":false,"fork":false,"pushed_at":"2025-05-05T15:44:59.000Z","size":222,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-30T05:57:43.106Z","etag":null,"topics":["ansi","api","ascii","ascii-art","cli","command-line","python","text","time-to-text"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CPScript.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-02T05:31:50.000Z","updated_at":"2025-08-25T17:26:35.000Z","dependencies_parsed_at":"2025-05-05T01:40:17.030Z","dependency_job_id":"d5311af9-df53-49b5-bb82-325ec8940f2c","html_url":"https://github.com/CPScript/ART","commit_stats":null,"previous_names":["cpscript/art"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/CPScript/ART","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CPScript%2FART","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CPScript%2FART/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CPScript%2FART/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CPScript%2FART/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CPScript","download_url":"https://codeload.github.com/CPScript/ART/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CPScript%2FART/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273685604,"owners_count":25149722,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-04T02:00:08.968Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ansi","api","ascii","ascii-art","cli","command-line","python","text","time-to-text"],"created_at":"2025-09-04T23:12:03.783Z","updated_at":"2025-09-04T23:12:07.165Z","avatar_url":"https://github.com/CPScript.png","language":"Python","readme":"# ART: ASCII Rendering Toolkit\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"https://img.shields.io/badge/python-3.7%2B-green.svg\" alt=\"Python 3.7+\"/\u003e\n\u003c/p\u003e\n\n## Enterprise Architecture Overview\n\n\"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.\n\n### Core Technology Stack\n\n- High-performance image processing subsystem\n- Advanced Unicode character mapping engine\n- ANSI color implementation architecture\n- Terminal-aware adaptive rendering\n- Stream-optimized I/O protocol\n\n## Installation Protocol\n\n### Development Implementation (recomended)\n\n```bash\ngit clone https://github.com/CPScript/ART\ncd ART/art\npip install -e .\n```\n\n## Feature Implementation Matrix\n\n- **Dynamic Symbol Mapping**: Configurable character sets for precision intensity mapping\n- **Color Preservation Technology**: ANSI color sequence generation with 16.7M color depth\n- **Dimension Control Protocol**: Multiple scaling strategies with terminal-aware rendering\n- **Format Transcoding Engine**: Support for all standard image formats via Pillow integration\n- **I/O Streaming Architecture**: UNIX-compatible filtering with stdin/stdout capabilities\n- **Background Control System**: Custom background color specification with RGB precision\n\n## Quick Implementation Reference\n\n```bash\n# Basic implementation with default parameters\nart image.jpg\n\n# Enhanced rendering with color preservation\nart image.jpg -u\n\n# Enterprise-grade rendering with optimized parameters\nart image.jpg -c \" .:-=+*#%@\" -s 2 -w 80 -H 40 -u -r -b \"40,40,40\" --filter lanczos\n```\n\n## Command-Line Protocol Specification\n\nThe ART command-line interface implements a comprehensive parameter architecture for maximum rendering control:\n\n```\nART [OPTIONS] [IMAGE_PATH]\n```\n\n### Positional Parameters\n\n| Parameter | Description | Implementation Notes |\n|-----------|-------------|---------------------|\n| `IMAGE_PATH` | Source image for transformation | Optional; Reads from STDIN if omitted |\n\n### Option Implementation Specification\n\n| Short Form | Long Form | Type | Default | Description |\n|------------|-----------|------|---------|-------------|\n| `-c` | `--symbols` | String | `\" .,-~!;:=*\u0026%$@#\"` | Character intensity mapping set (lightest to darkest) |\n| `-s` | `--scale` | Integer | `4` | Image dimension reduction factor (higher values = smaller output) |\n| `-w` | `--width` | Integer | Source-dependent | Explicit output width specification (columns) |\n| `-H` | `--height` | Integer | Source-dependent | Explicit output height specification (rows) |\n| `-b` | `--background` | String | None | Background color implementation (`r,g,b` or `#RRGGBB` format) |\n| `-r` | `--reverse` | Flag | `false` | Foreground/background color inversion |\n| `-u` | `--color` | Flag | `false` | ANSI color mode activation |\n| N/A | `--filter` | String | `nearest` | Resampling algorithm selection (`nearest`, `bilinear`, `bicubic`, `lanczos`) |\n| `-v` | `--version` | Flag | N/A | Version identification |\n| N/A | `--help` | Flag | N/A | Command documentation display |\n\n### Complex Parameter Implementation Patterns\n\n#### Symbol Set Architecture (`-c`, `--symbols`)\n\nThe symbol set determines the character-to-intensity mapping protocol:\n\n```bash\n# Binary implementation (high contrast)\nart image.jpg -c \" #\"\n\n# Grayscale implementation (standard density)\nart image.jpg -c \" .:-=+*#%@\"\n\n# Extended implementation (maximum fidelity)\nart image.jpg -c \" .'`^\\\",:;Il!i\u003e\u003c~+_-?][}{1)(|/tfjrxnuvczXYUJCLQ0OZmwqpdbkhao*#MW\u00268%B@$\"\n```\n\n#### Dimension Control Architecture\n\nART implements multiple strategies for dimension management:\n\n```bash\n# Scale-based implementation (factor of 2 reduction)\nart image.jpg -s 2\n\n# Width-constrained implementation (height auto-scaled)\nart image.jpg -w 80\n\n# Fixed-dimension implementation\nart image.jpg -w 120 -H 60\n\n# Terminal-optimized implementation\nart image.jpg -w $(tput cols) -H $(( $(tput lines) - 2 ))\n```\n\n#### Color Management Architecture\n\n```bash\n# Standard color implementation\nart image.jpg -u\n\n# Background color implementation\nart image.jpg -u -b \"255,200,180\"\n\n# Color plane inversion implementation\nart image.jpg -u -r\n\n# Complete color control implementation\nart image.jpg -u -r -b \"#E0E0FF\"\n```\n\n#### Resampling Architecture Selection\n\n```bash\n# Performance-optimized implementation\nart image.jpg --filter nearest\n\n# Quality-optimized implementation\nart image.jpg --filter lanczos\n```\n\n# Enterprise-Level Implementation Guide: Solid Block Character Rendering in ART\n\n## Technical Implementation Architecture\n\nTo 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.\n\n## Block Character Implementation Specification\n\nThe Unicode specification provides several block characters designed specifically for terminal graphics rendering:\n\n| Unicode | Character | Description | Density |\n|---------|-----------|-------------|---------|\n| U+2588 | █ | FULL BLOCK | 100% |\n| U+2593 | ▓ | DARK SHADE | 75% |\n| U+2592 | ▒ | MEDIUM SHADE | 50% |\n| U+2591 | ░ | LIGHT SHADE | 25% |\n| U+0020 | ` ` | SPACE | 0% |\n\n## Core Implementation Patterns\n\n### 1. Single Block Implementation (Binary Representation)\n\nTo render the image using only full blocks (filled squares):\n\n```bash\nart image.jpg -c \"█\"\n```\n\nThis creates a high-contrast rendering where every character is a solid block, with color preservation if the `-u` flag is enabled.\n\n### 2. Gradient Block Implementation (Density-Based)\n\nFor a grayscale-like effect using block density:\n\n```bash\nart image.jpg -c \" ░▒▓█\"\n```\n\nThis implementation maps pixel intensity to progressively denser block characters, creating a gradient effect with five distinct levels.\n\n### 3. Solid Block with Color Implementation (Maximum Fidelity)\n\n```bash\nart image.jpg -c \"█\" -u\n```\n\nThis enterprise-grade implementation combines solid block characters with ANSI color preservation, creating a pixel-perfect terminal rendering at the character cell resolution.\n\n## Advanced Implementation Strategies\n\n### 1. Inverted Block Rendering\n\n```bash\nart image.jpg -c \"█\" -u -r -b \"0,0,0\"\n```\n\nThis implementation renders solid blocks with inverted color planes against a black background, maximizing contrast and visibility.\n\n### 2. Terminal-Optimized Block Rendering\n\n```bash\nart image.jpg -c \"█\" -u -w $(tput cols) -H $(( $(tput lines) - 2 ))\n```\n\nThis implementation dynamically adapts the block rendering to the current terminal dimensions, ensuring optimal display characteristics.\n\n### 3. Half-Block Implementation (Enhanced Resolution)\n\nFor terminals supporting Unicode, you can leverage half-block characters to effectively double the vertical resolution:\n\n```bash\nart image.jpg -c \"▀▄█\" -u -s 2\n```\n\nThis advanced implementation uses upper half-block (▀), lower half-block (▄), and full block (█) characters to create higher-resolution renderings within terminal constraints.\n\n## Performance Considerations\n\nThe solid block implementation pattern offers several performance advantages:\n\n1. **Rendering Efficiency**: Simpler character set reduces ASCII art generation computational overhead\n2. **Memory Optimization**: Single-character representation minimizes buffer size requirements\n3. **Display Optimization**: Block characters optimize terminal rendering capabilities\n4. **Bandwidth Conservation**: Reduced character set variety improves compression ratios for transmission\n\n## Implementation Examples\n\n### Standard Solid Block Implementation\n\n```bash\n# Basic solid block rendering\nart photo.jpg -c \"█\"\n\n# Color-preserving solid block rendering\nart photo.jpg -c \"█\" -u\n\n# Gradient block rendering with color\nart photo.jpg -c \" ░▒▓█\" -u\n```\n\n### Enterprise-Grade Block Rendering\n\n```bash\n# Maximum-resolution block rendering with color preservation\nart high_res_image.jpg -c \"█\" -u -s 1 --filter lanczos\n\n# Memory-optimized block rendering\nart large_image.jpg -c \"█\" -u -s 6 --filter nearest\n```\n\nThis comprehensive implementation guide provides the technical foundation for leveraging solid block characters in ART, enabling pixel-accurate terminal graphics rendering with optimal performance characteristics.\n\n## Programmatic Implementation Architecture\n\nART can be integrated into advanced processing pipelines via its Python API:\n\n```python\nfrom PIL import Image\nfrom art import Config, Symbols, COLORS, REVERSE, convert_image_to_ascii\nimport sys\n\nconfig = Config(\n    symbols=Symbols(list(\" .:-=+*#%@\")),\n    flags=COLORS | REVERSE,\n    background=ANSIColor(40, 40, 40)\n)\n\nimage = Image.open(\"image.jpg\")\n\nconvert_image_to_ascii(config, image, sys.stdout)\n```\n\n### Advanced In-Memory Text Representation\n\nFor sophisticated integration scenarios:\n\n```python\nfrom PIL import Image\nfrom art import Config, Symbols, COLORS, TextImage, convert_image_to_ascii\n\nconfig = Config(symbols=Symbols(list(\" .:-=+*#%@\")), flags=COLORS)\n\nimage = Image.open(\"image.jpg\")\nwidth, height = image.size\n\ntext_image = TextImage(config, width, height)\nconvert_image_to_ascii(config, image, text_image)\n\nprint(text_image)\n```\n\n## Pipeline Integration Architecture\n\n### Stream Processing Implementation\n\n```bash\ncat image.jpg | art -u \u003e output.txt\n\nconvert image.jpg -resize 50% -colorspace gray jpg:- | art -c \" .:-=+*#%@\" \u003e output.txt\n```\n\n### Batch Processing Protocol\n\n```bash\nfor img in *.jpg; do\n    output_file=\"${img%.jpg}.txt\"\n    art \"$img\" -u -s 4 \u003e \"$output_file\"\ndone\n```\n\n## Performance Optimization Matrix\n\n| Use Case | Command Implementation | Memory Complexity | Processing Efficiency |\n|----------|------------------------|-------------------|------------------------|\n| Maximum Quality | `-s 1 -u --filter lanczos` | O(wh) | O(wh log wh) |\n| Standard Display | `-s 4 -u` | O(wh/16) | O(wh/16) |\n| Memory Optimization | `-s 8 -c \" #\" --filter nearest` | O(wh/64) | O(wh/64) |\n| Color Preservation | `-u -c \"█\"` | O(wh) | O(wh) |\n\n## System Requirements Specification\n\n- Python 3.7 or higher\n- Pillow 9.0.0 or higher\n- ANSI-compatible terminal for color rendering\n- Unicode support for block character rendering\n\n## Development Protocol\n\n### Environment Configuration\n\n```bash\ngit clone https://github.com/CPScript/ART.git\ncd ART\npython -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\npip install -e \".[dev]\"\n```\n\n## Acknowledgments\n\n- Pillow project for image processing capabilities\n- Unicode Consortium for terminal graphics character specifications\n- ANSI Terminal Standard for color rendering protocol\n\n---\n\n\u003cp align=\"center\"\u003eMade with precision engineering for terminal graphics excellence\u003c/p\u003e\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcpscript%2Fart","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcpscript%2Fart","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcpscript%2Fart/lists"}