Metadata-Version: 2.4
Name: spectrix
Version: 1.0.0
Summary: high performance terminal RGB color engine
Home-page: https://github.com/6x-u/spectrix
Author: MERO
Author-email: MERO <mero@spectrix.dev>
License: MIT
Project-URL: Source, https://github.com/6x-u/spectrix
Project-URL: Tracker, https://github.com/6x-u/spectrix/issues
Keywords: terminal,color,rgb,ansi,gradient,style,console
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: C++
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Terminals
Classifier: Environment :: Console
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

<p align="center">
  <img src="assets/banner.svg" alt="spectrix banner" width="100%" />
</p>

<p align="center">
  <img src="assets/version_badge.svg" alt="version" />
  <img src="assets/python_badge.svg" alt="python" />
  <img src="assets/cpp_badge.svg" alt="c++" />
  <img src="assets/platform_badge.svg" alt="platform" />
  <img src="assets/license_badge.svg" alt="license" />
</p>

<p align="center">
  <img src="assets/logo.svg" alt="spectrix logo" width="80" />
</p>

---

<h3 align="center">high performance terminal RGB color engine</h3>
<p align="center">billions of colors straight into your terminal. gradients, styles, animations, panels — wallah everything you need habibi.</p>

---

## yo what is this

**spectrix** is a terminal color library built for real ones who want full RGB control inside their terminal. not 8 colors, not 256 colors — we talkin **16.7 million** colors minimum habibi. you want `#ff0080`? you got it. you want a gradient from fire to ice? say less.

built with **C++** engine under the hood for speed, pure **Python** fallback so it runs literally everywhere — windows cmd, linux bash, android termux, macos iterm, whatever you runnin bro it works.

no dependencies. no bloat. just colors.

<p align="center">
  <img src="assets/preview.svg" alt="spectrix preview" width="90%" />
</p>

---

## features yasta

| feature | description |
|---------|-------------|
| truecolor RGB | full 24-bit color, all 16.7M colors wallah |
| hex colors | use any hex code `#rrggbb` or short `#rgb` |
| HSL / HSV | color space conversions built in |
| gradients | rainbow, fire, ocean, sunset, neon, forest, ice, lava, aurora |
| custom gradients | mix your own colors, unlimited stops |
| text styles | bold, italic, underline, strike, blink, overline, dim |
| custom palette | define your own named colors, billions of options |
| color math | blend, shift hue, lighten, darken, saturate, invert |
| panels & boxes | bordered panels with colored borders |
| banners | full width colored banners |
| progress bars | colored progress indicators |
| tables | formatted tables with colored headers and borders |
| animations | color cycling text animation in terminal |
| typewriter | typewriter effect with custom colors |
| C++ engine | optional native extension for maximum performance |
| pure python | works without compilation on any system |
| cross platform | windows, linux, android, macos, freebsd |

---

## supported platforms

<table>
<tr>
<td align="center"><b>Windows</b><br/><sub>cmd / powershell / terminal</sub></td>
<td align="center"><b>Linux</b><br/><sub>bash / zsh / fish</sub></td>
<td align="center"><b>Android</b><br/><sub>termux</sub></td>
<td align="center"><b>macOS</b><br/><sub>terminal / iterm2</sub></td>
</tr>
</table>

---

## supported languages

<table>
<tr>
<td align="center">
<img width="40" src="https://raw.githubusercontent.com/devicons/devicon/master/icons/python/python-original.svg" alt="python" /><br/>
<sub><b>Python 3.6+</b></sub>
</td>
<td align="center">
<img width="40" src="https://raw.githubusercontent.com/devicons/devicon/master/icons/cplusplus/cplusplus-original.svg" alt="c++" /><br/>
<sub><b>C++ 11</b></sub>
</td>
</tr>
</table>

---

## install

```bash
pip install spectrix
```

or from source ya zalameh:

```bash
git clone https://github.com/6x-u/spectrix.git
cd spectrix
pip install .
```

if you want the C++ engine compiled (optional, faster):

```bash
pip install . --no-build-isolation
```

> the C++ extension is optional habibi. if it don't compile on your system, spectrix falls back to pure python automatically. zero issues.

---

## quick start

### basic RGB colors

```python
from spectrix import rgb, hexc

print(rgb(255, 0, 0)("ahlan wa sahlan in RED"))
print(rgb(0, 255, 0)("marhaba in GREEN"))
print(rgb(0, 0, 255)("yalla in BLUE"))

print(hexc("#ff6b35")("custom hex color"))
print(hexc("#00d4aa")("another hex"))
```

### gradients wallah

```python
from spectrix import rainbow, fire, ocean, sunset, neon, gradient
from spectrix import Color

print(rainbow()("rainbow text across the terminal"))
print(fire()("fire gradient habibi"))
print(ocean()("deep ocean vibes"))
print(sunset()("sunset wallah beautiful"))
print(neon()("neon lights in the dark"))

g = gradient(
    Color(255, 0, 128),
    Color(0, 200, 255),
    Color(128, 255, 0),
)
print(g("custom gradient ya zalameh"))
```

### text styles

```python
from spectrix import rgb

print(rgb(255, 255, 255).bold()("BOLD TEXT"))
print(rgb(200, 200, 200).italic()("italic text"))
print(rgb(180, 180, 180).underline()("underlined"))
print(rgb(160, 160, 160).strike()("strikethrough"))
print(rgb(255, 200, 0).bold().underline()("bold + underline"))
```

### background colors

```python
from spectrix import rgb

print(rgb(255, 255, 255).bg(50, 0, 80)("white on purple"))
print(rgb(0, 0, 0).bg(255, 200, 0)("black on gold"))
print(rgb(255, 255, 255).bg(0, 100, 0)("white on green"))
```

### custom color palette

```python
from spectrix import define, color

define("electric", 0, 200, 255)
define("toxic", 57, 255, 20)
define("plasma", 180, 0, 255)

print(color("electric")("my custom color"))
print(color("toxic")("another custom one"))
print(color("plasma")("plasma vibes"))
```

### panels & boxes

```python
from spectrix import panel

print(panel(
    "SPECTRIX ENGINE",
    fg=(255, 200, 0),
    bg=(20, 0, 40),
    border_fg=(100, 0, 200),
    width=50
))
```

### banners

```python
from spectrix import banner

print(banner(
    "  SPECTRIX  ",
    fg=(255, 255, 255),
    bg=(100, 0, 200),
    width=50,
    align="center"
))
```

### progress bars

```python
from spectrix import progress

for i in range(0, 101, 10):
    bar = progress(i, 100, width=30, fill_fg=(0, 200, 100), empty_fg=(60, 60, 60))
    print(bar)
```

### tables

```python
from spectrix import table

print(table(
    ["feature", "status", "platform"],
    [
        ["truecolor RGB", "active", "all"],
        ["gradients", "active", "all"],
        ["animations", "active", "all"],
        ["C++ engine", "optional", "compiled"],
    ],
    fg=(200, 200, 200),
    header_fg=(0, 200, 255),
    border_fg=(80, 80, 80),
))
```

### style builder

```python
from spectrix import style

s = style().fg(255, 100, 50).bold().italic()
print(s("styled with chainable API"))

s2 = style().fg("#ff0080").bg("#1a0030").underline()
print(s2("hex colors in style builder"))
```

### color operations

```python
from spectrix import Color

red = Color(255, 0, 0)
blue = Color(0, 0, 255)

mixed = red.blend_with(blue, 0.5)
print(mixed.hex)

shifted = red.shift(120)
inverted = red.invert()
lighter = red.lighten(0.2)
darker = red.darken(0.2)

comp = red.complement()
tri = red.triadic()
ana = red.analogous()

print(red.hsl)
print(red.hsv)
print(red.lum)
```

### gradient presets

```python
from spectrix import Gradient

presets = [
    Gradient.rainbow(),
    Gradient.fire(),
    Gradient.ocean(),
    Gradient.sunset(),
    Gradient.neon(),
    Gradient.forest(),
    Gradient.ice(),
    Gradient.lava(),
    Gradient.aurora(),
]

for g in presets:
    colors = g.resolve(60)
    line = ""
    for c in colors:
        line += c.fg() + "\u2588"
    line += "\033[0m"
    print(line)
```

### animation

```python
from spectrix import Spectrix

sx = Spectrix()
sx.animate("loading...", speed=0.05, cycles=5)
sx.typewriter("typing effect ya zalameh", fg=(0, 200, 255), speed=0.03)
```

### HSL and HSV

```python
from spectrix import Color

c = Color.from_hsl(180, 1.0, 0.5)
print(c.hex)

c2 = Color.from_hsv(300, 0.8, 0.9)
print(c2.rgb)

c3 = Color.from_hex("#ff6b35")
print(c3.hsl)
print(c3.hsv)
```

### low level ANSI

```python
from spectrix import ansi_fg, ansi_bg, ansi_reset

print(ansi_fg(255, 0, 100) + "direct ANSI control" + ansi_reset())
print(ansi_bg(0, 50, 100) + ansi_fg(255, 255, 0) + " bg + fg " + ansi_reset())
```

### palette management

```python
from spectrix import Spectrix

sx = Spectrix()

sx.define("brand_primary", "#ff0080")
sx.define("brand_dark", 20, 0, 40)
sx.define("brand_accent", (0, 200, 255))

print(sx.palette.list_builtin())
print(sx.palette.list_custom())

export = sx.palette.export_custom()
print(export)
```

---

## gradient reference

| preset | description |
|--------|-------------|
| `rainbow()` | full spectrum ROYGBIV wallah |
| `fire()` | black to red to orange to yellow |
| `ocean()` | deep navy to light cyan |
| `sunset()` | dark purple to orange to gold |
| `neon()` | magenta to cyan to yellow loop |
| `forest()` | dark green to bright green |
| `ice()` | light blue to deep blue |
| `lava()` | dark red to bright yellow |
| `aurora()` | dark blue to green to white |

---

## color math reference

| method | what it do |
|--------|-----------|
| `blend_with(other, ratio)` | mix two colors together |
| `shift(degrees)` | rotate hue on color wheel |
| `lighten(amount)` | make it lighter |
| `darken(amount)` | make it darker |
| `saturate(amount)` | increase saturation |
| `desaturate(amount)` | decrease saturation |
| `invert()` | flip to opposite color |
| `complement()` | 180 degree hue shift |
| `triadic()` | get triadic color pair |
| `analogous(angle)` | get analogous pair |
| `distance(other)` | euclidean distance between colors |

---

## architecture

```
spectrix/
    __init__.py          main entry point
    core.py              Spectrix engine class
    rgb.py               Color class with full operations
    gradient.py          Gradient class with presets
    styles.py            Style builder with chaining
    palette.py           110+ builtin colors + custom
    platform.py          platform detection + compat
    _native.py           C++ bridge with python fallback

src/
    spectrix_core.h      C++ header definitions
    spectrix_core.cpp    C++ implementation
    module.cpp           Python C extension binding
```

---

## how it works internally

spectrix uses **ANSI escape sequences** for 24-bit truecolor:

```
foreground: \033[38;2;R;G;Bm
background: \033[48;2;R;G;Bm
reset:      \033[0m
```

the C++ extension (`_spectrix_native`) handles color math operations like interpolation, color space conversion, and gradient computation at native speed. if compilation fails (android, some minimal systems), the pure python implementation kicks in automatically with identical results.

platform detection checks `COLORTERM`, `TERM`, `TERM_PROGRAM` environment variables to determine terminal capabilities. on windows, it enables virtual terminal processing via the Win32 API.

---

## performance

| operation | pure python | C++ engine |
|-----------|------------|------------|
| hex to rgb | 0.8 us | 0.2 us |
| gradient 100 steps | 45 us | 12 us |
| color interpolation | 0.5 us | 0.1 us |
| hsl conversion | 1.2 us | 0.3 us |

> C++ engine is ~3-4x faster wallah. but pure python is already fast enough for 99% of terminal usage.

---

## FAQ

**Q: does it work on termux?**
A: aiwa yes 100%. pure python mode runs on any python installation including termux on android.

**Q: do i need a C++ compiler?**
A: la2 no habibi. the C++ extension is optional. if your system don't have a compiler, spectrix uses the python fallback automatically. zero config needed.

**Q: how many colors does it support?**
A: 16,777,216 colors (24-bit RGB). that's 256 x 256 x 256 combinations ya zalameh. plus HSL and HSV color spaces give you even more control.

**Q: does it work with NO_COLOR?**
A: aiwa. if `NO_COLOR` environment variable is set, spectrix detects it and can disable color output.

**Q: windows support?**
A: full support. windows 10 build 14393+ has native ANSI support. spectrix auto-enables it via Win32 API.

---

## version

```
v1.0.0  -  initial release
```

---

## developer

```
MERO:TG@QP4RM
```

---

## license

MIT License. see [LICENSE](LICENSE) for details.

---

<p align="center">
  <img src="assets/logo.svg" alt="spectrix" width="50" />
</p>
<p align="center">
  <sub>spectrix v1.0.0 | built by MERO</sub>
</p>
