| Name | chromatic-python JSON |
| Version |
0.2.0
JSON |
| download |
| home_page | None |
| Summary | ANSI art image processing and colored terminal text |
| upload_time | 2025-02-03 16:11:46 |
| maintainer | None |
| docs_url | None |
| author | crypt0lith |
| requires_python | >=3.12 |
| license | MIT License Copyright (c) 2024 crypt0lith Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
ansi
ascii
art
font
image
terminal
parser
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
[](https://pypi.org/project/chromatic-python/)
[](https://pepy.tech/projects/chromatic-python)
[](https://mypy-lang.org/)
Chromatic is a library for processing and transforming ANSI escape sequences (colored terminal text).
It offers a collection of algorithms and types for a variety of use cases:
- Image-to-ASCII / Image-to-ANSI conversions.
- ANSI art rendering, with support for user-defined fonts.
- A `ColorStr` type which enables precise low-level control over ANSI-escaped strings through a convenient interface.
- [colorama](https://github.com/tartley/colorama/)-style wrappers (`Fore`, `Back`, `Style`).
- Parametrization of ANSI color bit formats, allowing arbitrary conversion between 16-color, 256-color, and true-color (RGB) colorspace on any object implementing a `colorbytes` buffer.
- Et Cetera 😲
### Usage
#### ColorStr
```python
from chromatic import ColorStr
base_str = 'hello world'
red_fg = ColorStr(base_str, 0xFF0000)
assert red_fg.base_str == base_str
assert red_fg.rgb_dict == {'fg': (0xFF, 0, 0)}
assert red_fg.ansi == b'\x1b[38;5;196m'
```
`ColorStr` can handle different signatures for `color_spec`:
```python
from chromatic import ColorStr
assert all(
ColorStr('*', cs) == ColorStr('*', 0xFF0000)
for cs in [b'\x1b[38;5;196m', b'\xff\x00\x00', (0xFF, 0, 0), {'fg': 0xFF0000}]
)
```
The ANSI color format can be given as an argument, or returned by `ColorStr.as_ansi_type()` as a new instance.
```python
from chromatic import ColorStr, ansicolor24Bit, ansicolor4Bit
truecolor = ColorStr('*', 0xFF0000, ansi_type=ansicolor24Bit)
a_16color = truecolor.as_ansi_type(ansicolor4Bit)
# each ansi color format has an alias that can be used in place of the type object
assert a_16color == truecolor.as_ansi_type('4b')
assert truecolor.ansi_format is ansicolor24Bit and truecolor.ansi == b'\x1b[38;2;255;0;0m'
assert a_16color.ansi_format is ansicolor4Bit and a_16color.ansi == b'\x1b[31m'
```
Adding and removing specific ANSI codes from the escape sequence:
```python
import chromatic as cm
boring_str = cm.ColorStr('hello world')
assert boring_str.ansi == b''
bold_str = boring_str + cm.SgrParameter.BOLD
assert bold_str.ansi == b'\x1b[1m'
# use ColorStr.update_sgr() to remove and add SGR values
unbold_str = bold_str.update_sgr(cm.SgrParameter.BOLD)
assert unbold_str == boring_str
assert bold_str == unbold_str.update_sgr(cm.SgrParameter.BOLD)
```
#### Image-to-ANSI conversion
Converting an image into an array of ANSI-escaped characters, then rendering the ANSI array as another image:
```python
from chromatic.color import ansicolor4Bit
from chromatic.ascii import ansi2img, img2ansi
from chromatic.data import UserFont, butterfly
input_img = butterfly()
font = UserFont.IBM_VGA_437_8X16
# by default, `char_set` would be sorted based on the relative weight of glyphs in the font
# but because `sort_glyphs` is set to False, `char_set` will be directly mapped to the image brightness
# | <- index 0 is the 'darkest'
char_set = r"'·,•-_→+<>ⁿ*%⌂7√Iï∞πbz£9yîU{}1αHSw♥æ?GX╕╒éà⌡MF╝╩ΘûǃQ½☻Ŷ┤▄╪║▒█"
# index -1 is the 'brightest' -> |
ansi_array = img2ansi(input_img, font, sort_glyphs=False, char_set=char_set, ansi_type=ansicolor4Bit, factor=200)
# ansi2img() returns a PIL.Image.Image object
ansi_img = ansi2img(ansi_array, font, font_size=16)
ansi_img.show()
```
### Installation
Install the package using `pip`:
```bash
pip install chromatic-python
```
Raw data
{
"_id": null,
"home_page": null,
"name": "chromatic-python",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "ansi, ascii, art, font, image, terminal, parser",
"author": "crypt0lith",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/34/74/3f0eb7e321a904865690295558cae6bb54a67bd1941f570f5bf1c60802c8/chromatic_python-0.2.0.tar.gz",
"platform": null,
"description": "\r\n\r\n[](https://pypi.org/project/chromatic-python/)\r\n\r\n[](https://pepy.tech/projects/chromatic-python)\r\n[](https://mypy-lang.org/)\r\n\r\nChromatic is a library for processing and transforming ANSI escape sequences (colored terminal text).\r\n\r\nIt offers a collection of algorithms and types for a variety of use cases:\t\r\n- Image-to-ASCII / Image-to-ANSI conversions.\r\n- ANSI art rendering, with support for user-defined fonts.\r\n- A `ColorStr` type which enables precise low-level control over ANSI-escaped strings through a convenient interface.\r\n- [colorama](https://github.com/tartley/colorama/)-style wrappers (`Fore`, `Back`, `Style`).\r\n- Parametrization of ANSI color bit formats, allowing arbitrary conversion between 16-color, 256-color, and true-color (RGB) colorspace on any object implementing a `colorbytes` buffer.\r\n- Et Cetera \ud83d\ude32\r\n\r\n### Usage\r\n#### ColorStr\r\n```python\r\nfrom chromatic import ColorStr\r\n\r\nbase_str = 'hello world'\r\n\r\nred_fg = ColorStr(base_str, 0xFF0000)\r\n\r\nassert red_fg.base_str == base_str\r\nassert red_fg.rgb_dict == {'fg': (0xFF, 0, 0)}\r\nassert red_fg.ansi == b'\\x1b[38;5;196m'\r\n```\r\n\r\n`ColorStr` can handle different signatures for `color_spec`:\r\n```python\r\nfrom chromatic import ColorStr\r\n\r\nassert all(\r\n\tColorStr('*', cs) == ColorStr('*', 0xFF0000)\r\n for cs in [b'\\x1b[38;5;196m', b'\\xff\\x00\\x00', (0xFF, 0, 0), {'fg': 0xFF0000}]\r\n)\r\n```\r\n\r\nThe ANSI color format can be given as an argument, or returned by `ColorStr.as_ansi_type()` as a new instance.\r\n```python\r\nfrom chromatic import ColorStr, ansicolor24Bit, ansicolor4Bit\r\n\r\ntruecolor = ColorStr('*', 0xFF0000, ansi_type=ansicolor24Bit)\r\na_16color = truecolor.as_ansi_type(ansicolor4Bit)\r\n\r\n# each ansi color format has an alias that can be used in place of the type object\r\nassert a_16color == truecolor.as_ansi_type('4b')\r\n\r\nassert truecolor.ansi_format is ansicolor24Bit and truecolor.ansi == b'\\x1b[38;2;255;0;0m'\r\nassert a_16color.ansi_format is ansicolor4Bit and a_16color.ansi == b'\\x1b[31m'\r\n```\r\n\r\nAdding and removing specific ANSI codes from the escape sequence:\r\n```python\r\nimport chromatic as cm\r\n\r\nboring_str = cm.ColorStr('hello world')\r\n\r\nassert boring_str.ansi == b''\r\n\r\nbold_str = boring_str + cm.SgrParameter.BOLD\r\nassert bold_str.ansi == b'\\x1b[1m'\r\n\r\n# use ColorStr.update_sgr() to remove and add SGR values\r\nunbold_str = bold_str.update_sgr(cm.SgrParameter.BOLD)\r\nassert unbold_str == boring_str\r\nassert bold_str == unbold_str.update_sgr(cm.SgrParameter.BOLD)\r\n```\r\n\r\n#### Image-to-ANSI conversion\r\n\r\nConverting an image into an array of ANSI-escaped characters, then rendering the ANSI array as another image:\r\n```python\r\nfrom chromatic.color import ansicolor4Bit\r\nfrom chromatic.ascii import ansi2img, img2ansi\r\nfrom chromatic.data import UserFont, butterfly\r\n\r\ninput_img = butterfly()\r\n\r\nfont = UserFont.IBM_VGA_437_8X16\r\n\r\n# by default, `char_set` would be sorted based on the relative weight of glyphs in the font\r\n# but because `sort_glyphs` is set to False, `char_set` will be directly mapped to the image brightness\r\n# | <- index 0 is the 'darkest'\r\nchar_set = r\"'\u00b7,\u2022-_\u2192+<>\u207f*%\u23027\u221aI\u00ef\u221e\u03c0bz\u00a39y\u00eeU{}1\u03b1HSw\u2665\u00e6?GX\u2555\u2552\u00e9\u00e0\u2321MF\u255d\u2569\u0398\u00fb\u00c7\u0192Q\u00bd\u263b\u00c5\u00b6\u2524\u2584\u256a\u2551\u2592\u2588\"\r\n# index -1 is the 'brightest' -> |\r\n\r\nansi_array = img2ansi(input_img, font, sort_glyphs=False, char_set=char_set, ansi_type=ansicolor4Bit, factor=200)\r\n\r\n# ansi2img() returns a PIL.Image.Image object\r\nansi_img = ansi2img(ansi_array, font, font_size=16)\r\nansi_img.show()\r\n```\r\n\r\n### Installation\r\nInstall the package using `pip`:\r\n```bash\r\npip install chromatic-python\r\n```\r\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2024 crypt0lith Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.",
"summary": "ANSI art image processing and colored terminal text",
"version": "0.2.0",
"project_urls": {
"Homepage": "https://github.com/crypt0lith/chromatic"
},
"split_keywords": [
"ansi",
" ascii",
" art",
" font",
" image",
" terminal",
" parser"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2f1b8732f5d42964e15bad5f01299de547663451b4e09baf232d12b52f00c1ca",
"md5": "68bd32cef1b53e362684ce314c0e27ef",
"sha256": "c006187fb847968dee9d08cf0c75edfa27b0c5e03fe55b3824cf5c81597510ef"
},
"downloads": -1,
"filename": "chromatic_python-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "68bd32cef1b53e362684ce314c0e27ef",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 975414,
"upload_time": "2025-02-03T16:11:45",
"upload_time_iso_8601": "2025-02-03T16:11:45.029306Z",
"url": "https://files.pythonhosted.org/packages/2f/1b/8732f5d42964e15bad5f01299de547663451b4e09baf232d12b52f00c1ca/chromatic_python-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "34743f0eb7e321a904865690295558cae6bb54a67bd1941f570f5bf1c60802c8",
"md5": "4ffcb8ecb323fcaa3f8d39e1ba2a11ad",
"sha256": "761deff081619262398cc79346091c79c089e803bd9fb57608163b1c29c94c75"
},
"downloads": -1,
"filename": "chromatic_python-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "4ffcb8ecb323fcaa3f8d39e1ba2a11ad",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 1108726,
"upload_time": "2025-02-03T16:11:46",
"upload_time_iso_8601": "2025-02-03T16:11:46.508756Z",
"url": "https://files.pythonhosted.org/packages/34/74/3f0eb7e321a904865690295558cae6bb54a67bd1941f570f5bf1c60802c8/chromatic_python-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-03 16:11:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "crypt0lith",
"github_project": "chromatic",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "chromatic-python"
}
