| Name | climage JSON |
| Version |
0.2.2
JSON |
| download |
| home_page | None |
| Summary | Convert images to beautiful ANSI escape codes |
| upload_time | 2024-09-29 06:09:32 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.2 |
| license | MIT License |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# CLImage 📷
Convert images to beautiful ANSI escape codes for display in command line interfaces.
Available as both a CLI application and a Python library.
# Features
- Custom sized images
- ASCII or Unicode support
- Unicode enables 4x more detail
- 8/16/256/Truecolor support, for a wider gamut of colors
- Selectable system palettes to adjust for user terminal themes
- Fast color lookup with KDTrees & memoization
# Usage
CLImage is available as both a standalone CLI program, or available for import as a Python3 library.
## CLI Program
By default converting an image will output in 256 color, as 80 columns, and ASCII (for reasonable compatibility).
```bash
$ climage image.png
```
A nicer image can be obtained when enabling unicode and truecolor flags.
```bash
$ climage --unicode --truecolour image.png
```
For display in TTYs such as the Linux terminal before starting X11 (also accessible by Ctrl-Alt-F3, etc), you should restrict yourself to 8 color, and ASCII only. As 8 and 16 colors are solely constructed out of system colors (often set by the terminal theme), it is recommended to select a palette for these, depending on what you have selected.
```bash
$ climage --8color warhol.png --palette solarized
```
Further options may be found by running `climage --help`
## Python Library
It is recommended that you use the Python library if converting a large number of images. Simple usage:
```python3
import climage
# Convert an image to a 50 character wide image.
output = climage.convert('image.png', is_unicode=True, width=50)
print(output)
# Convert an image using 8 color mode 100 columns wide, and write to file.
climage.to_file('image.png', 'out.txt', is_8color=True, width=100)
```
### Formats
The API also supports supplying a [Pillow](https://pypi.org/project/Pillow/) Image object, or a [numpy](https://numpy.org/) array representing an image.
These formats may be useful if you have already loaded from file, or are applying complex filters to the images prior to rendering.
Pillow Images can be converted via the `convert_pil` function:
```python3
import climage
from PIL import Image
# It is good practice to convert to RGB, before conversion. Climage supports
# RGBA also, but will render as if the alpha channel is completely opaque.
# Attempting to convert greyscale or other formats (e.g. RBG) will fail, or
# present an invalid result.
img = Image.open('image.png').convert('RGB')
output = climage.convert_pil(img, is_unicode=True)
print(output)
```
Similarly, numpy arrays are converted using the `convert_arr` function. In the example below we use Pillow to generate the numpy array, but any row-major array whose element represents an RGB triplet. Each colour is represented by a number in the range [0,255].
```python3
import climage
from PIL import Image
# Convert the image into 50px * 50px, as the convert_array function does not
# perform resizing.
img = Image.open('image.png').convert('RGB').resize((50, 50))
arr = np.array(img)
output = climage.convert_array(arr, is_unicode=True)
print(output)
```
Python lists are also accepted:
```
from climage import convert_array
# Simple 2x2 image showing raw python lists are usable too.
print(
convert_array([
[[128, 128, 0], [0, 128, 128]],
[[0, 128, 0], [0, 0, 128]],
], is_unicode=True)
)
```
Output:
### Helpers
To provide you more expressiveness and flexibility, various helper methods are exposed.
```python3
from climage import color_to_flags, color_types, convert
# color_to_flags allows you to easily define the color option required by
# convert. Accepts a value from the `color_types` enum, which has the following
# options:
# - color_types.truecolor
# - color_types.color256
# - color_types.color16
# - color_types.color8
print(convert('teapot.png', is_unicode=True, **color_to_flags(color_types.truecolor)))
```
Output:
```python3
from climage import get_ansi_pixel, get_reset_code, color_types
# get_ansi_pixel lets you to convert an RGB color to the ANSI escape code
# sequence for representing that colour as a pixel. Similar to the convert
# functions, by default converts using a 256 color palette, and does not use
# the unicode characters.
# This call will print 2 characters wide, as it is not unicode.
pix = get_ansi_pixel(
# Violet
(148, 0, 211),
ctype=color_types.truecolor,
)
# If you are printing this pixel singularly, you will want to reset the color
# back to normal. If you are wishing to print a bunch sequentially (as in, on
# the same line), you should append the reset code at the end.
print(pix + get_reset_code())
```
Output:
```python3
from climage import get_dual_unicode_ansi_pixels, get_reset_code, color_types
# get_dual_unicode_ansi_pixels is the unicode character equivalent of
# get_ansi_pixel. This accepts two colours, one for the upper pixel, and one
# for the bottom pixel.
pixels = get_dual_unicode_ansi_pixels(
# Green
(0, 128, 0),
# Red
(128, 0, 0),
ctype=color_types.color256,
palette="solarized",
)
print(pixels + get_reset_code())
```
Output:
### Additional interfacing
As `climage` can convert arbitrary images in memory, converting images on the Internet is possible using the `requests` library:
```python3
import requests
import climage
from io import BytesIO
response = requests.get('https://www.python.org/static/community_logos/python-logo-master-v3-TM-flattened.png')
# Convert to RGB, as files on the Internet may be greyscale, which are not
# supported.
img = Image.open(BytesIO(response.content)).convert('RGB')
# Convert the image to 80col, in 256 color mode, using unicode for higher def.
converted = climage.convert_pil(img, is_unicode=True)
print(converted)
```
Output:
Note that caching the image may be more efficient for multiple invocations.
# Future:
- [ ] Improve performance in 256 color mapping, see [here](https://github.com/pnappa/CLImage/issues/1)
- Ideas? Let me know by filing an issue. :)
Raw data
{
"_id": null,
"home_page": null,
"name": "climage",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.2",
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": "Patrick Nappa <patricknappa@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/be/47/ecdf0faae89e98a0b15a7acb04d6ce0c24dfb30ddd60d30283ac493a65ef/climage-0.2.2.tar.gz",
"platform": null,
"description": "# CLImage \ud83d\udcf7\n\nConvert images to beautiful ANSI escape codes for display in command line interfaces.\n\nAvailable as both a CLI application and a Python library.\n\n\n\n# Features\n - Custom sized images\n - ASCII or Unicode support\n - Unicode enables 4x more detail\n - 8/16/256/Truecolor support, for a wider gamut of colors\n - Selectable system palettes to adjust for user terminal themes\n - Fast color lookup with KDTrees & memoization\n\n# Usage\n\nCLImage is available as both a standalone CLI program, or available for import as a Python3 library.\n\n## CLI Program\n\nBy default converting an image will output in 256 color, as 80 columns, and ASCII (for reasonable compatibility).\n```bash\n$ climage image.png\n```\n\n\n\nA nicer image can be obtained when enabling unicode and truecolor flags.\n```bash\n$ climage --unicode --truecolour image.png\n```\n\n\nFor display in TTYs such as the Linux terminal before starting X11 (also accessible by Ctrl-Alt-F3, etc), you should restrict yourself to 8 color, and ASCII only. As 8 and 16 colors are solely constructed out of system colors (often set by the terminal theme), it is recommended to select a palette for these, depending on what you have selected.\n```bash\n$ climage --8color warhol.png --palette solarized\n```\n\n\nFurther options may be found by running `climage --help`\n\n## Python Library\n\nIt is recommended that you use the Python library if converting a large number of images. Simple usage:\n\n```python3\nimport climage\n\n# Convert an image to a 50 character wide image.\noutput = climage.convert('image.png', is_unicode=True, width=50)\nprint(output)\n\n# Convert an image using 8 color mode 100 columns wide, and write to file.\nclimage.to_file('image.png', 'out.txt', is_8color=True, width=100)\n```\n\n### Formats\nThe API also supports supplying a [Pillow](https://pypi.org/project/Pillow/) Image object, or a [numpy](https://numpy.org/) array representing an image.\n\nThese formats may be useful if you have already loaded from file, or are applying complex filters to the images prior to rendering.\n\nPillow Images can be converted via the `convert_pil` function:\n\n```python3\nimport climage\nfrom PIL import Image\n\n# It is good practice to convert to RGB, before conversion. Climage supports\n# RGBA also, but will render as if the alpha channel is completely opaque.\n# Attempting to convert greyscale or other formats (e.g. RBG) will fail, or\n# present an invalid result.\nimg = Image.open('image.png').convert('RGB')\noutput = climage.convert_pil(img, is_unicode=True)\nprint(output)\n```\n\nSimilarly, numpy arrays are converted using the `convert_arr` function. In the example below we use Pillow to generate the numpy array, but any row-major array whose element represents an RGB triplet. Each colour is represented by a number in the range [0,255].\n\n```python3\nimport climage\nfrom PIL import Image\n\n# Convert the image into 50px * 50px, as the convert_array function does not\n# perform resizing.\nimg = Image.open('image.png').convert('RGB').resize((50, 50))\narr = np.array(img)\noutput = climage.convert_array(arr, is_unicode=True)\nprint(output)\n\n```\n\nPython lists are also accepted:\n\n```\nfrom climage import convert_array\n\n# Simple 2x2 image showing raw python lists are usable too.\nprint(\n convert_array([\n [[128, 128, 0], [0, 128, 128]],\n [[0, 128, 0], [0, 0, 128]],\n ], is_unicode=True)\n)\n```\n\nOutput:\n\n\n\n### Helpers\n\nTo provide you more expressiveness and flexibility, various helper methods are exposed.\n\n```python3\nfrom climage import color_to_flags, color_types, convert\n\n# color_to_flags allows you to easily define the color option required by\n# convert. Accepts a value from the `color_types` enum, which has the following\n# options:\n# - color_types.truecolor\n# - color_types.color256\n# - color_types.color16\n# - color_types.color8\nprint(convert('teapot.png', is_unicode=True, **color_to_flags(color_types.truecolor)))\n\n```\n\nOutput:\n\n\n\n```python3\nfrom climage import get_ansi_pixel, get_reset_code, color_types\n\n# get_ansi_pixel lets you to convert an RGB color to the ANSI escape code\n# sequence for representing that colour as a pixel. Similar to the convert\n# functions, by default converts using a 256 color palette, and does not use\n# the unicode characters.\n# This call will print 2 characters wide, as it is not unicode.\npix = get_ansi_pixel(\n # Violet\n (148, 0, 211),\n ctype=color_types.truecolor,\n)\n# If you are printing this pixel singularly, you will want to reset the color\n# back to normal. If you are wishing to print a bunch sequentially (as in, on\n# the same line), you should append the reset code at the end.\nprint(pix + get_reset_code())\n```\n\nOutput:\n\n\n\n\n```python3\nfrom climage import get_dual_unicode_ansi_pixels, get_reset_code, color_types\n\n# get_dual_unicode_ansi_pixels is the unicode character equivalent of\n# get_ansi_pixel. This accepts two colours, one for the upper pixel, and one\n# for the bottom pixel.\npixels = get_dual_unicode_ansi_pixels(\n # Green\n (0, 128, 0),\n # Red\n (128, 0, 0),\n ctype=color_types.color256,\n palette=\"solarized\",\n)\nprint(pixels + get_reset_code())\n```\n\nOutput:\n\n\n\n### Additional interfacing\nAs `climage` can convert arbitrary images in memory, converting images on the Internet is possible using the `requests` library:\n\n```python3\nimport requests\nimport climage\nfrom io import BytesIO\n\nresponse = requests.get('https://www.python.org/static/community_logos/python-logo-master-v3-TM-flattened.png')\n# Convert to RGB, as files on the Internet may be greyscale, which are not\n# supported.\nimg = Image.open(BytesIO(response.content)).convert('RGB')\n# Convert the image to 80col, in 256 color mode, using unicode for higher def.\nconverted = climage.convert_pil(img, is_unicode=True)\nprint(converted)\n```\n\nOutput:\n\n\n\nNote that caching the image may be more efficient for multiple invocations.\n\n# Future:\n - [ ] Improve performance in 256 color mapping, see [here](https://github.com/pnappa/CLImage/issues/1)\n - Ideas? Let me know by filing an issue. :)\n\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "Convert images to beautiful ANSI escape codes",
"version": "0.2.2",
"project_urls": {
"Documentation": "http://github.com/pnappa/CLImage",
"Issues": "http://github.com/pnappa/CLImage/issues",
"Source": "http://github.com/pnappa/CLImage"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "84d46080fb8fdba671ac2e8b542746c0ea7039eb288459a648fa3be3cf2e7b20",
"md5": "33609cb2b481a9c5ca36d910697156d9",
"sha256": "0a820c7e9c51aa0f720dd3039247848db3c42ebf62475407ec33442e7919b6ab"
},
"downloads": -1,
"filename": "climage-0.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "33609cb2b481a9c5ca36d910697156d9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.2",
"size": 12145,
"upload_time": "2024-09-29T06:09:29",
"upload_time_iso_8601": "2024-09-29T06:09:29.909121Z",
"url": "https://files.pythonhosted.org/packages/84/d4/6080fb8fdba671ac2e8b542746c0ea7039eb288459a648fa3be3cf2e7b20/climage-0.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "be47ecdf0faae89e98a0b15a7acb04d6ce0c24dfb30ddd60d30283ac493a65ef",
"md5": "f8e1a0d8a2cabdf07a59e40af173ab94",
"sha256": "e6116b2f5f3d313adb0856657efe4a6d119e2218cdef23c28a993d94b871ab8e"
},
"downloads": -1,
"filename": "climage-0.2.2.tar.gz",
"has_sig": false,
"md5_digest": "f8e1a0d8a2cabdf07a59e40af173ab94",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.2",
"size": 13663,
"upload_time": "2024-09-29T06:09:32",
"upload_time_iso_8601": "2024-09-29T06:09:32.269649Z",
"url": "https://files.pythonhosted.org/packages/be/47/ecdf0faae89e98a0b15a7acb04d6ce0c24dfb30ddd60d30283ac493a65ef/climage-0.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-29 06:09:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pnappa",
"github_project": "CLImage",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "climage"
}
