spectrix 1.0.0

high performance terminal RGB color engine

---

high performance terminal RGB color engine

billions of colors straight into your terminal. gradients, styles, animations, panels — wallah everything you need habibi.

---

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.

---

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

Windows cmd / powershell / terminal

Linux bash / zsh / fish

Android termux

macOS terminal / iterm2

---

supported languages

Python 3.6+

C++ 11

---

install

pip install spectrix

or from source ya zalameh:

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

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

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

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

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

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

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

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

from spectrix import panel

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

banners

from spectrix import banner

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

progress bars

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

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

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

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

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

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

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

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

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 for details.

---

_{spectrix v1.0.0 | built by MERO}