[](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 for low-level control over ANSI SGR strings.
- [colorama](https://github.com/tartley/colorama/)-style wrappers (`Fore`, `Back`, `Style`).
- Conversion between 16-color, 256-color, and true-color (RGB) ANSI colorspace via the `colorbytes` type.
- Et Cetera 😲
### Usage
#### Image-to-ANSI conversion
Convert an image into a 2d ANSI string array, and render the ANSI array as image:
```python
from chromatic.color import ansicolor4Bit
from chromatic.image import ansi2img, img2ansi
from chromatic.data import userfont, butterfly
input_img = butterfly()
font = userfont['vga437']
# `char_set` is used to translate luminance to characters
# | <- index 0 is the 'darkest'
char_set = r"'·,•-_→+<>ⁿ*%⌂7√Iï∞πbz£9yîU{}1αHSw♥æ?GX╕╒éà⌡MF╝╩ΘûǃQ½☻Ŷ┤▄╪║▒█"
# index -1 is the 'brightest' -> |
# returns list[list[ColorStr]]
ansi_array = img2ansi(
input_img,
font,
sort_glyphs=False, # map `char_set` as-is
char_set=char_set,
ansi_type=ansicolor4Bit,
factor=200,
)
# print your image to stdout
print(*map(''.join, ansi_array), sep="\x1b[0m\n")
# returns a PIL.Image.Image object
ansi_img = ansi2img(ansi_array, font, font_size=16)
ansi_img.show()
```
#### ColorStr
```python
from chromatic import ColorStr
base_str = 'hello world'
red_fg = ColorStr(base_str, 0xFF0000, ansi_type='8b')
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` will parse raw SGR sequences, and accepts different types for `fg` and `bg`:
```python
from chromatic import ColorStr
red_fg = ColorStr('[*]', 0xFF0000, ansi_type='8b')
assert red_fg == ColorStr(b"\x1b[38;5;196m[*]")
assert red_fg == ColorStr('[*]', fg=(0xFF, 0, 0), ansi_type='8b')
```
ANSI color format can be specified with `ColorStr(ansi_type=...)`, or as a new object via `ColorStr.as_ansi_type()`:
```python
from chromatic import ColorStr, ansicolor4Bit, ansicolor24Bit, ansicolor8Bit
# each colorbytes type has an alias that you can use
assert all(
ansi_type.alias == alias
for ansi_type, alias in [
(ansicolor4Bit, '4b'),
(ansicolor8Bit, '8b'),
(ansicolor24Bit, '24b'),
]
)
truecolor = ColorStr('*', 0xFF0000, ansi_type=ansicolor24Bit)
a_16color = truecolor.as_ansi_type(ansicolor4Bit)
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 SGR parameters from a `ColorStr`:
```python
import chromatic as cm
regular_str = cm.ColorStr('hello world')
assert regular_str.ansi == b''
bold_str = regular_str.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 == regular_str
assert bold_str == unbold_str + cm.SgrParameter.BOLD # __add__ can also be used
```
### Installation
Install the package using `pip`:
```bash
pip install chromatic-python
```
### Credits
Banner artwork: [main rules by Crasher (2002)](https://16colo.rs/pack/galza-14/CRS-MAIN.ANS)
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/e6/cb/65499c7b7587edff3b43f51db4b59dded8b49d0c4e96aecf894238bada4d/chromatic_python-0.4.1.tar.gz",
"platform": null,
"description": "\n\n[](https://pypi.org/project/chromatic-python/)\n\n[](https://pepy.tech/projects/chromatic-python)\n[](https://mypy-lang.org/)\n\nChromatic is a library for processing and transforming ANSI escape sequences (colored terminal text).\n\nIt offers a collection of algorithms and types for a variety of use cases:\t\n- Image-to-ASCII / Image-to-ANSI conversions.\n- ANSI art rendering, with support for user-defined fonts.\n- A `ColorStr` type for low-level control over ANSI SGR strings.\n- [colorama](https://github.com/tartley/colorama/)-style wrappers (`Fore`, `Back`, `Style`).\n- Conversion between 16-color, 256-color, and true-color (RGB) ANSI colorspace via the `colorbytes` type.\n- Et Cetera \ud83d\ude32\n\n### Usage\n#### Image-to-ANSI conversion\n\nConvert an image into a 2d ANSI string array, and render the ANSI array as image:\n```python\nfrom chromatic.color import ansicolor4Bit\nfrom chromatic.image import ansi2img, img2ansi\nfrom chromatic.data import userfont, butterfly\n\ninput_img = butterfly()\nfont = userfont['vga437']\n\n# `char_set` is used to translate luminance to characters \n# | <- index 0 is the 'darkest'\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\"\n# index -1 is the 'brightest' -> |\n\n# returns list[list[ColorStr]]\nansi_array = img2ansi(\n\tinput_img,\n\tfont,\n\tsort_glyphs=False,\t# map `char_set` as-is\n\tchar_set=char_set,\n\tansi_type=ansicolor4Bit,\n\tfactor=200,\n)\n\n# print your image to stdout\nprint(*map(''.join, ansi_array), sep=\"\\x1b[0m\\n\")\n\n# returns a PIL.Image.Image object\nansi_img = ansi2img(ansi_array, font, font_size=16)\nansi_img.show()\n```\n\n#### ColorStr\n```python\nfrom chromatic import ColorStr\n\nbase_str = 'hello world'\n\nred_fg = ColorStr(base_str, 0xFF0000, ansi_type='8b')\n\nassert red_fg.base_str == base_str\nassert red_fg.rgb_dict == {'fg': (0xFF, 0, 0)}\nassert red_fg.ansi == b'\\x1b[38;5;196m'\n```\n\n`ColorStr` will parse raw SGR sequences, and accepts different types for `fg` and `bg`:\n```python\nfrom chromatic import ColorStr\n\nred_fg = ColorStr('[*]', 0xFF0000, ansi_type='8b')\n\nassert red_fg == ColorStr(b\"\\x1b[38;5;196m[*]\")\nassert red_fg == ColorStr('[*]', fg=(0xFF, 0, 0), ansi_type='8b')\n```\n\nANSI color format can be specified with `ColorStr(ansi_type=...)`, or as a new object via `ColorStr.as_ansi_type()`:\n```python\nfrom chromatic import ColorStr, ansicolor4Bit, ansicolor24Bit, ansicolor8Bit\n\n# each colorbytes type has an alias that you can use \nassert all(\n\tansi_type.alias == alias\n\tfor ansi_type, alias in [\n (ansicolor4Bit, '4b'),\n\t\t(ansicolor8Bit, '8b'),\n\t\t(ansicolor24Bit, '24b'),\n\t]\n)\n\ntruecolor = ColorStr('*', 0xFF0000, ansi_type=ansicolor24Bit)\na_16color = truecolor.as_ansi_type(ansicolor4Bit)\n\nassert a_16color == truecolor.as_ansi_type('4b')\nassert truecolor.ansi_format is ansicolor24Bit and truecolor.ansi == b'\\x1b[38;2;255;0;0m'\nassert a_16color.ansi_format is ansicolor4Bit and a_16color.ansi == b'\\x1b[31m'\n```\n\nAdding and removing SGR parameters from a `ColorStr`:\n```python\nimport chromatic as cm\n\nregular_str = cm.ColorStr('hello world')\n\nassert regular_str.ansi == b''\n\nbold_str = regular_str.bold()\n\nassert bold_str.ansi == b'\\x1b[1m'\n\n# use ColorStr.update_sgr() to remove and add SGR values\nunbold_str = bold_str.update_sgr(cm.SgrParameter.BOLD)\n\nassert unbold_str == regular_str\nassert bold_str == unbold_str + cm.SgrParameter.BOLD\t# __add__ can also be used\n```\n\n### Installation\nInstall the package using `pip`:\n```bash\npip install chromatic-python\n```\n\n### Credits\nBanner artwork: [main rules by Crasher (2002)](https://16colo.rs/pack/galza-14/CRS-MAIN.ANS)\n",
"bugtrack_url": null,
"license": null,
"summary": "ANSI art image processing and colored terminal text",
"version": "0.4.1",
"project_urls": {
"Homepage": "https://github.com/crypt0lith/chromatic"
},
"split_keywords": [
"ansi",
" ascii",
" art",
" font",
" image",
" terminal",
" parser"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "3b7ad82ab1a7945405794fc731c07e0997c75f78e93dc34f8540ccf937fdc2ba",
"md5": "de6f6d1db1a627cf9e4de4bbb255bb9e",
"sha256": "a9ebf392df919c2b1bf3a8989d5663d2baa006dd4b49bd0982e964153b53ad9e"
},
"downloads": -1,
"filename": "chromatic_python-0.4.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "de6f6d1db1a627cf9e4de4bbb255bb9e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 921101,
"upload_time": "2025-09-13T03:11:03",
"upload_time_iso_8601": "2025-09-13T03:11:03.997728Z",
"url": "https://files.pythonhosted.org/packages/3b/7a/d82ab1a7945405794fc731c07e0997c75f78e93dc34f8540ccf937fdc2ba/chromatic_python-0.4.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e6cb65499c7b7587edff3b43f51db4b59dded8b49d0c4e96aecf894238bada4d",
"md5": "4e5ea98ed9ef76204782a721e396dd68",
"sha256": "892a4132524100ae43d4ad8155bc44c7b206ec2f6adb5c6b48e33c98fa0a6adf"
},
"downloads": -1,
"filename": "chromatic_python-0.4.1.tar.gz",
"has_sig": false,
"md5_digest": "4e5ea98ed9ef76204782a721e396dd68",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 1171981,
"upload_time": "2025-09-13T03:11:06",
"upload_time_iso_8601": "2025-09-13T03:11:06.267761Z",
"url": "https://files.pythonhosted.org/packages/e6/cb/65499c7b7587edff3b43f51db4b59dded8b49d0c4e96aecf894238bada4d/chromatic_python-0.4.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-13 03:11:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "crypt0lith",
"github_project": "chromatic",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "fonttools",
"specs": [
[
"==",
"4.59.0"
]
]
},
{
"name": "imageio",
"specs": [
[
"==",
"2.37.0"
]
]
},
{
"name": "joblib",
"specs": [
[
"==",
"1.5.1"
]
]
},
{
"name": "lazy-loader",
"specs": [
[
"==",
"0.4"
]
]
},
{
"name": "networkx",
"specs": [
[
"==",
"3.5"
]
]
},
{
"name": "numpy",
"specs": [
[
"==",
"2.2.6"
]
]
},
{
"name": "opencv-python",
"specs": [
[
"==",
"4.12.0.88"
]
]
},
{
"name": "packaging",
"specs": [
[
"==",
"25.0"
]
]
},
{
"name": "pillow",
"specs": [
[
"==",
"11.3.0"
]
]
},
{
"name": "scikit-image",
"specs": [
[
"==",
"0.25.2"
]
]
},
{
"name": "scikit-learn",
"specs": [
[
"==",
"1.7.1"
]
]
},
{
"name": "scipy",
"specs": [
[
"==",
"1.16.1"
]
]
},
{
"name": "threadpoolctl",
"specs": [
[
"==",
"3.6.0"
]
]
},
{
"name": "tifffile",
"specs": [
[
"==",
"2025.6.11"
]
]
}
],
"lcname": "chromatic-python"
}
JSON
