ogfade

Advanced text color manipulation library for terminal-based applications.

Table of Contents

Overview · Installation · Quick Start · Function Reference · Advanced Usage · Performance · Technical Details · Contributing · License · Contact

Overview

ogfade provides high-performance ANSI color gradient generation and text effects for ASCII art and terminal output. Built for developers who need professional-grade text styling with minimal overhead.

Key Features:

• 25+ built-in color effects and gradients
• Custom gradient creation with RGB color stops
• Adjustable intensity and animation support
• Filter effects and color palette management
• Zero external dependencies
• Cross-platform compatibility

Installation

From PyPI (Recommended)

pip install ogfade

From Source

git clone https://github.com/ogcae/ogfade.git
cd ogfade
pip install -e .

Manual Installation

# Download and extract
tar -xzf dist/ogfade-3.0.0.tar.gz
cd ogfade-3.0.0
pip install .

Quick Start

import ogfade

# Your ASCII art or text
text = """
  ______    ______   ________  ______   _______   ________ 
 /      \  /      \ /        |/      \ /       \ /        |
/$$$$$$  |/$$$$$$  |$$$$$$$$//$$$$$$  |$$$$$$$  |$$$$$$$$/ 
$$ |  $$ |$$ | _$$/ $$ |__   $$ |__$$ |$$ |  $$ |$$ |__    
$$ |  $$ |$$ |/    |$$    |  $$    $$ |$$ |  $$ |$$    |   
$$ |  $$ |$$ |$$$$ |$$$$$/   $$$$$$$$ |$$ |  $$ |$$$$$/    
$$ \__$$ |$$ \__$$ |$$ |     $$ |  $$ |$$ |__$$ |$$ |_____ 
$$    $$/ $$    $$/ $$ |     $$ |  $$ |$$    $$/ $$       |
 $$$$$$/   $$$$$$/  $$/      $$/   $$/ $$$$$$$/  $$$$$$$$/                                                
"""

# Apply gradient effects
print(ogfade.rainbow(text))
print(ogfade.sunset(text))
print(ogfade.ocean(text))

Function Reference

Basic Gradients

Function	Description	Color Range
blackwhite()	Black to white gradient	⚫ → ⚪
purplepink()	Purple to pink transition	🟣 → 🩷
greenblue()	Green to blue gradient	�� → 🔵
pinkred()	Pink to red gradient	🩷 → 🔴
purpleblue()	Purple to blue gradient	🟣 → 🔵
water()	Ocean water effect	🌊
fire()	Fire gradient	🔥
brazil()	Brazil flag colors	🇧🇷
random_colors()	Random color per character	🎲
sunset()	Sunset gradient	🌅
ocean()	Deep ocean gradient	🌊
forest()	Forest gradient	🌲
neon()	Cyberpunk neon effect	⚡
metallic()	Metallic gradient	🛠️
rainbow()	Full spectrum rainbow	🌈

Advanced Functions

Function	Description	Parameters
custom_gradient()	User-defined color gradients	text, colors: List[Tuple[int, int, int]]
fade_intensity()	Adjustable fade intensity	text, intensity: float = 1.0
animated_gradient()	Generate animation frames	text, frames: int = 10
color_blend()	Color transition variations	text, color1, color2, steps: int = 10
text_wave()	Wave distortion effect	text, amplitude: int = 2
glitch_effect()	Digital glitch simulation	text, intensity: float = 0.1
retro_gradient()	Retro computer styling	text
aurora()	Aurora borealis effect	text
heatmap()	Heat map color scheme	text
mono_shift()	Monochromatic variations	text, shift: int = 1
apply_filter()	Predefined filter effects	text, filter_type: str
create_palette()	Create color palette	colors: List[Tuple[int, int, int]]
apply_palette()	Apply consistent palette	text, palette: dict, style: str = "gradient"

Advanced Usage

Custom Gradients

import ogfade

# Define custom color stops
colors = [
    (255, 0, 0),    # Red
    (255, 165, 0),  # Orange  
    (255, 255, 0),  # Yellow
    (0, 255, 0),    # Green
    (0, 0, 255),    # Blue
    (128, 0, 128)   # Purple
]

text = "Custom Gradient Text"
result = ogfade.custom_gradient(text, colors)
print(result)

Intensity Control

# Fine-tune fade intensity (0.0 to 1.0)
light = ogfade.fade_intensity(text, 0.3)
normal = ogfade.fade_intensity(text, 0.7) 
strong = ogfade.fade_intensity(text, 1.0)

Animation Frames

# Generate animation frames for smooth transitions
frames = ogfade.animated_gradient(text, frames=15)
for frame in frames:
    print(frame)
    time.sleep(0.1)  # Add timing for animation

Filter Effects

# Apply predefined filters
vintage = ogfade.apply_filter(text, "vintage")
sepia = ogfade.apply_filter(text, "sepia")
cool_tone = ogfade.apply_filter(text, "cool")
matrix_style = ogfade.apply_filter(text, "matrix")

Color Palettes

# Create and use consistent color palettes
palette = ogfade.create_palette([
    (255, 100, 100),  # Primary
    (100, 255, 100),  # Secondary  
    (100, 100, 255),  # Accent
    (50, 50, 50)      # Background
])

styled_text = ogfade.apply_palette(text, palette)

Run the example:

python example.py

Performance

• Zero external dependencies - Pure Python implementation
• Optimized ANSI generation - Minimal memory footprint
• Fast color interpolation - Efficient RGB calculations
• Scalable processing - Handles large text blocks efficiently

Benchmark results (processing 1000 characters):

• Rainbow gradient: ~0.005s
• Custom gradient: ~0.008s
• Glitch effect: ~0.012s

Technical Details

Color Format

All colors use RGB tuples: (red, green, blue) where each component ranges from 0-255.

# Valid color formats
red = (255, 0, 0)
green = (0, 255, 0)
blue = (0, 0, 255)
custom = (128, 64, 32)

ANSI Implementation

Uses ANSI escape sequences (\033[38;2;r;g;bm) for true color support in modern terminals.

• Foreground colors: \033[38;2;r;g;bm
• Reset: \033[0m
• True color: 24-bit RGB values

System Requirements

• Python: 3.7 or higher
• Terminal: ANSI color support (most modern terminals)
• Memory: ~2MB for library + text processing
• CPU: Minimal requirements (interpreted Python)

Contributing

Contributions are welcome! Please see our Contributing Guide for details.

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Development Setup

git clone https://github.com/ogcae/ogfade.git
cd ogfade
pip install -e ".[dev]"

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contact

EMAIL

For support, feature requests, or bug reports, please open an issue on GitHub.