Metadata-Version: 2.4
Name: chromatic-python
Version: 0.2.2
Summary: ANSI art image processing and colored terminal text
Author: crypt0lith
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.
Project-URL: Homepage, https://github.com/crypt0lith/chromatic
Keywords: ansi,ascii,art,font,image,terminal,parser
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: networkx~=3.4.2
Requires-Dist: numpy~=2.2.6
Requires-Dist: pillow~=11.2.1
Requires-Dist: opencv-python~=4.11.0.86
Requires-Dist: scikit-image~=0.25.2
Requires-Dist: scikit-learn~=1.6.1
Requires-Dist: fonttools~=4.58.0
Requires-Dist: scipy~=1.15.3
Dynamic: license-file

![image](/logo/logo.PNG)

[![image](https://img.shields.io/pypi/v/chromatic-python)](https://pypi.org/project/chromatic-python/)
![image](https://img.shields.io/pypi/pyversions/chromatic-python)
[![image](https://static.pepy.tech/badge/chromatic-python)](https://pepy.tech/projects/chromatic-python)
[![image](https://mypy-lang.org/static/mypy_badge.svg)](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
```
