# img-characterize
Convert images to character art with support for multiple character sets and formats.
## Features
- Multiple character sets (ASCII, Emoji, Chinese, etc.)
- Color and black/white modes
- Multiple output formats (PNG, JPG, TXT)
- Batch processing support
- Automatic character selection based on brightness
- GUI interface for easy use
- Command-line interface for automation
- Image optimization capabilities
- Large image subdivision support
## Installation
```bash
pip install img-characterize
```
## Quick Start
### Command Line
Convert a single image:
```bash
img-characterize -i image.jpg -s ascii
```
Convert multiple images:
```bash
img-characterize -i image1.jpg image2.png -s emoji --color
```
Convert all images in a directory:
```bash
img-characterize -i ./images/ -s chinese --color --optimize
```
### Python API
```python
from img_characterize import convert_image
# Simple conversion
output_path = convert_image(
"input.jpg",
"output",
character_set="ascii"
)
# Advanced options
output_path = convert_image(
"input.jpg",
"output",
character_set="emoji",
detail_level=15,
complexity=20,
color_mode=True,
subdivide=True,
optimize=True,
empty_char=True,
output_formats=["png", "txt"]
)
```
## Command Line Options
- `-i, --input`: Input image files or directories
- `-s, --character-set`: Character set to use (default: ascii)
- Available sets: ascii, arabic, braille, chinese, cyrillic, emoji, hangul, hiragana, katakana, kanji, latin, numbers, numbers+, roman, simple
- `-d, --detail-level`: Detail level (character size in pixels, default: 12)
- `-c, --complexity`: Number of different characters to use (default: 12)
- `--color`: Enable color output
- `--subdivide`: Subdivide large images
- `--optimize`: Optimize output files
- `--empty-char`: Include empty character for darker areas
- `-f, --formats`: Output formats (png, jpg, txt)
## Character Sets
Each character set has different characteristics suitable for different types of images:
- `ascii`: Good for general use, wide brightness range (2-81)
- `emoji`: Best for color images, largest brightness range (31-173)
- `chinese`: Excellent detail, wide range (0-107)
- `braille`: Compact representation, small range (3-18)
- `numbers`: Clean look, moderate range (21-43)
- `roman`: Serif style, good contrast (27-81)
## Development
### Setup Development Environment
1. Clone the repository:
```bash
git clone https://github.com/kodu-ai/img-characterize.git
cd img-characterize
```
2. Create a virtual environment:
```bash
python -m venv venv
source venv/bin/activate # Linux/Mac
venv\Scripts\activate # Windows
```
3. Install development dependencies:
```bash
pip install -e ".[dev]"
```
### Running Tests
```bash
pytest tests/
```
### Building Documentation
```bash
cd docs
make html
```
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests
5. Submit a pull request
## License
MIT License - see LICENSE file for details.
## Acknowledgments
- PIL/Pillow for image processing
- NumPy for numerical operations
- The open-source community for font resources
## Troubleshooting
### Common Issues
1. **Font Not Found**
- Ensure required system fonts are installed
- Use custom fonts by specifying font_path
2. **Memory Issues**
- Use --subdivide for large images
- Reduce detail_level for faster processing
3. **Quality Issues**
- Adjust complexity for more/fewer characters
- Try different character sets
- Enable color mode for color-rich images
### Error Messages
- "Font not found": Install required system fonts
- "Image too large": Use --subdivide option
- "Invalid character set": Check available sets
## Support
- GitHub Issues: Bug reports and feature requests
- Documentation: Full API reference and examples
- Email: support@kodu.ai
## Roadmap
- Additional character sets
- Custom character set support
- Animation support
- Web interface
- Cloud processing support
Raw data
{
"_id": null,
"home_page": "https://github.com/kodu-ai/characterize",
"name": "img-characterize",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "image processing, ascii art, character art, image conversion, text art",
"author": "Kodu AI",
"author_email": "info@kodu.ai",
"download_url": "https://files.pythonhosted.org/packages/79/9e/be0f10d90aa3f1121be71d99e9feaf9479f947264c15b8359c0959689659/img_characterize-0.3.2.tar.gz",
"platform": null,
"description": "# img-characterize\r\n\r\nConvert images to character art with support for multiple character sets and formats.\r\n\r\n## Features\r\n\r\n- Multiple character sets (ASCII, Emoji, Chinese, etc.)\r\n- Color and black/white modes\r\n- Multiple output formats (PNG, JPG, TXT)\r\n- Batch processing support\r\n- Automatic character selection based on brightness\r\n- GUI interface for easy use\r\n- Command-line interface for automation\r\n- Image optimization capabilities\r\n- Large image subdivision support\r\n\r\n## Installation\r\n\r\n```bash\r\npip install img-characterize\r\n```\r\n\r\n## Quick Start\r\n\r\n### Command Line\r\n\r\nConvert a single image:\r\n```bash\r\nimg-characterize -i image.jpg -s ascii\r\n```\r\n\r\nConvert multiple images:\r\n```bash\r\nimg-characterize -i image1.jpg image2.png -s emoji --color\r\n```\r\n\r\nConvert all images in a directory:\r\n```bash\r\nimg-characterize -i ./images/ -s chinese --color --optimize\r\n```\r\n\r\n### Python API\r\n\r\n```python\r\nfrom img_characterize import convert_image\r\n\r\n# Simple conversion\r\noutput_path = convert_image(\r\n \"input.jpg\",\r\n \"output\",\r\n character_set=\"ascii\"\r\n)\r\n\r\n# Advanced options\r\noutput_path = convert_image(\r\n \"input.jpg\",\r\n \"output\",\r\n character_set=\"emoji\",\r\n detail_level=15,\r\n complexity=20,\r\n color_mode=True,\r\n subdivide=True,\r\n optimize=True,\r\n empty_char=True,\r\n output_formats=[\"png\", \"txt\"]\r\n)\r\n```\r\n\r\n## Command Line Options\r\n\r\n- `-i, --input`: Input image files or directories\r\n- `-s, --character-set`: Character set to use (default: ascii)\r\n - Available sets: ascii, arabic, braille, chinese, cyrillic, emoji, hangul, hiragana, katakana, kanji, latin, numbers, numbers+, roman, simple\r\n- `-d, --detail-level`: Detail level (character size in pixels, default: 12)\r\n- `-c, --complexity`: Number of different characters to use (default: 12)\r\n- `--color`: Enable color output\r\n- `--subdivide`: Subdivide large images\r\n- `--optimize`: Optimize output files\r\n- `--empty-char`: Include empty character for darker areas\r\n- `-f, --formats`: Output formats (png, jpg, txt)\r\n\r\n## Character Sets\r\n\r\nEach character set has different characteristics suitable for different types of images:\r\n\r\n- `ascii`: Good for general use, wide brightness range (2-81)\r\n- `emoji`: Best for color images, largest brightness range (31-173)\r\n- `chinese`: Excellent detail, wide range (0-107)\r\n- `braille`: Compact representation, small range (3-18)\r\n- `numbers`: Clean look, moderate range (21-43)\r\n- `roman`: Serif style, good contrast (27-81)\r\n\r\n## Development\r\n\r\n### Setup Development Environment\r\n\r\n1. Clone the repository:\r\n```bash\r\ngit clone https://github.com/kodu-ai/img-characterize.git\r\ncd img-characterize\r\n```\r\n\r\n2. Create a virtual environment:\r\n```bash\r\npython -m venv venv\r\nsource venv/bin/activate # Linux/Mac\r\nvenv\\Scripts\\activate # Windows\r\n```\r\n\r\n3. Install development dependencies:\r\n```bash\r\npip install -e \".[dev]\"\r\n```\r\n\r\n### Running Tests\r\n\r\n```bash\r\npytest tests/\r\n```\r\n\r\n### Building Documentation\r\n\r\n```bash\r\ncd docs\r\nmake html\r\n```\r\n\r\n## Contributing\r\n\r\n1. Fork the repository\r\n2. Create a feature branch\r\n3. Make your changes\r\n4. Run tests\r\n5. Submit a pull request\r\n\r\n## License\r\n\r\nMIT License - see LICENSE file for details.\r\n\r\n## Acknowledgments\r\n\r\n- PIL/Pillow for image processing\r\n- NumPy for numerical operations\r\n- The open-source community for font resources\r\n\r\n## Troubleshooting\r\n\r\n### Common Issues\r\n\r\n1. **Font Not Found**\r\n - Ensure required system fonts are installed\r\n - Use custom fonts by specifying font_path\r\n\r\n2. **Memory Issues**\r\n - Use --subdivide for large images\r\n - Reduce detail_level for faster processing\r\n\r\n3. **Quality Issues**\r\n - Adjust complexity for more/fewer characters\r\n - Try different character sets\r\n - Enable color mode for color-rich images\r\n\r\n### Error Messages\r\n\r\n- \"Font not found\": Install required system fonts\r\n- \"Image too large\": Use --subdivide option\r\n- \"Invalid character set\": Check available sets\r\n\r\n## Support\r\n\r\n- GitHub Issues: Bug reports and feature requests\r\n- Documentation: Full API reference and examples\r\n- Email: support@kodu.ai\r\n\r\n## Roadmap\r\n\r\n- Additional character sets\r\n- Custom character set support\r\n- Animation support\r\n- Web interface\r\n- Cloud processing support\r\n",
"bugtrack_url": null,
"license": null,
"summary": "Convert images to character art with support for multiple character sets and formats",
"version": "0.3.2",
"project_urls": {
"Bug Reports": "https://github.com/kodu-ai/characterize/issues",
"Documentation": "https://github.com/kodu-ai/characterize/blob/main/README.md",
"Homepage": "https://github.com/kodu-ai/characterize",
"Source": "https://github.com/kodu-ai/characterize"
},
"split_keywords": [
"image processing",
" ascii art",
" character art",
" image conversion",
" text art"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9315418c4eb6ef6b9ce3db107da6d173ec1eaf51097f9c54e0a98362df3aacd8",
"md5": "a437cc1b4ee96a604d9162d7f6b9d859",
"sha256": "880e5f0313997698588c14826c1b40895b17d4cd6c6bdbe149d56eb68ee09fed"
},
"downloads": -1,
"filename": "img_characterize-0.3.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a437cc1b4ee96a604d9162d7f6b9d859",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 16463,
"upload_time": "2024-11-22T03:02:02",
"upload_time_iso_8601": "2024-11-22T03:02:02.274198Z",
"url": "https://files.pythonhosted.org/packages/93/15/418c4eb6ef6b9ce3db107da6d173ec1eaf51097f9c54e0a98362df3aacd8/img_characterize-0.3.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "799ebe0f10d90aa3f1121be71d99e9feaf9479f947264c15b8359c0959689659",
"md5": "8eaef810f4d6750f151cc8bc4f3c9ad8",
"sha256": "9f9e2e7182c7b95618aea1c17aecc19b80321ed89ba256e4b8a5fe103e2a9c6a"
},
"downloads": -1,
"filename": "img_characterize-0.3.2.tar.gz",
"has_sig": false,
"md5_digest": "8eaef810f4d6750f151cc8bc4f3c9ad8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 15795,
"upload_time": "2024-11-22T03:02:03",
"upload_time_iso_8601": "2024-11-22T03:02:03.944757Z",
"url": "https://files.pythonhosted.org/packages/79/9e/be0f10d90aa3f1121be71d99e9feaf9479f947264c15b8359c0959689659/img_characterize-0.3.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-22 03:02:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kodu-ai",
"github_project": "characterize",
"github_not_found": true,
"lcname": "img-characterize"
}
JSON
