chroma-forge

A comprehensive color conversion library for Rust that provides seamless conversion between various color formats including RGB, Hex, HSL, HSV, CMYK, and Minecraft color codes.

Features

• Multiple Color Formats: RGB/RGBA, Hex, HSL, HSV, CMYK
• Minecraft Color Codes: Legacy codes (§, &) and modern hex formats
• Color Utilities: Luminance calculation, dark/light detection, contrasting colors
• Color Manipulation: Blending, darkening, lightening
• Zero Dependencies: Pure Rust implementation
• Comprehensive Error Handling: Custom error types with detailed messages
• Extensive Testing: Full test coverage for all conversion methods

Installation

Add this to your Cargo.toml:

[dependencies]
chroma-forge = "1.0.0"

Quick Start

use chroma_forge::Color;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create colors from different formats
    let hex_color = Color::from_hex("#FF5733")?;
    let rgb_color = Color::from_rgb(255, 87, 51);
    let hsl_color = Color::from_hsl(10.0, 100.0, 60.0)?;

    // Convert between formats
    println!("Hex: {}", hex_color.to_hex());        // #FF5733
    println!("RGB: {}", hex_color.to_rgb());        // rgb(255, 87, 51)
    println!("HSL: {}", hex_color.to_hsl());        // hsl(10.0°, 100.0%, 60.0%)

    Ok(())
}

Color Format Support

RGB/RGBA

let color = Color::from_rgb(255, 87, 51);
let color_with_alpha = Color::from_rgba(255, 87, 51, 0.8);
let rgb = color.to_rgb();

Hex Colors

Supports multiple hex formats:

let color1 = Color::from_hex("#FF5733")?;     // Full format
let color2 = Color::from_hex("FF5733")?;      // Without #
let color3 = Color::from_hex("#F53")?;        // Short format
let color4 = Color::from_hex("#FF5733CC")?;   // With alpha

let hex = color.to_hex();                     // #FF5733
let hex_alpha = color.to_hex_alpha();         // #FF5733FF

HSL (Hue, Saturation, Lightness)

let color = Color::from_hsl(220.0, 100.0, 50.0)?; // Blue
let hsl = color.to_hsl();

HSV (Hue, Saturation, Value)

let color = Color::from_hsv(220.0, 100.0, 100.0)?; // Blue
let hsv = color.to_hsv();

CMYK (Cyan, Magenta, Yellow, Key/Black)

let color = Color::from_cmyk(100.0, 0.0, 0.0, 0.0)?; // Cyan
let cmyk = color.to_cmyk();

Minecraft Color Codes

chroma-forge provides comprehensive support for Minecraft's color system, including both legacy and modern formats.

Legacy Color Codes

Supports all 16 standard Minecraft colors with both § and & prefixes:

// Legacy format parsing
let red = Color::from_minecraft_code("§c")?;       // Red
let blue = Color::from_minecraft_code("&1")?;      // Dark Blue
let yellow = Color::from_minecraft_code("e")?;     // Yellow (no prefix)

// Convert to legacy format (finds closest match)
let mc_code = color.to_minecraft_code();           // "§c"

Modern Hex Formats

Supports Minecraft's modern hex color formats:

// Modern hex format
let color1 = Color::from_minecraft_code("&#FF5733")?;

// Alternate hex format
let color2 = Color::from_minecraft_code("&x&F&F&5&7&3&3")?;

// Convert to modern formats
let mc_hex = color.to_minecraft_hex();             // "&#FF5733"
let mc_alt = color.to_minecraft_hex_alt();         // "&x&F&F&5&7&3&3"

Minecraft Color Constants

Pre-defined constants for all Minecraft colors:

let colors = [
    Color::MC_BLACK,        // §0
    Color::MC_DARK_BLUE,    // §1
    Color::MC_DARK_GREEN,   // §2
    Color::MC_DARK_AQUA,    // §3
    Color::MC_DARK_RED,     // §4
    Color::MC_DARK_PURPLE,  // §5
    Color::MC_GOLD,         // §6
    Color::MC_GRAY,         // §7
    Color::MC_DARK_GRAY,    // §8
    Color::MC_BLUE,         // §9
    Color::MC_GREEN,        // §a
    Color::MC_AQUA,         // §b
    Color::MC_RED,          // §c
    Color::MC_LIGHT_PURPLE, // §d
    Color::MC_YELLOW,       // §e
    Color::MC_WHITE,        // §f
];

Color Utilities

Luminance and Brightness

let color = Color::from_hex("#FF5733")?;

let luminance = color.luminance();              // 0.0 to 1.0
let is_dark = color.is_dark();                  // true/false
let is_light = color.is_light();                // true/false

// Get contrasting color for text overlay
let contrast = color.contrasting_text_color();  // Black or white

Color Manipulation

let color = Color::from_hex("#4080FF")?;

// Darken/lighten by percentage
let darker = color.darken(30.0);                // 30% darker
let lighter = color.lighten(30.0);              // 30% lighter

// Blend two colors
let red = Color::RED;
let blue = Color::BLUE;
let purple = red.blend(&blue, 0.5);             // 50% blend

Color Constants

Common colors are available as constants:

let colors = [
    Color::BLACK,
    Color::WHITE,
    Color::RED,
    Color::GREEN,
    Color::BLUE,
    Color::YELLOW,
    Color::CYAN,
    Color::MAGENTA,
];

Error Handling

chroma-forge uses a comprehensive error system:

use chroma_forge::{Color, ColorError};

match Color::from_hex("invalid") {
    Ok(color) => println!("Color: {}", color.to_hex()),
    Err(ColorError::InvalidHexFormat) => println!("Invalid hex format"),
    Err(ColorError::InvalidHexLength) => println!("Invalid hex length"),
    Err(e) => println!("Other error: {}", e),
}

Error types include:

• InvalidHexFormat
• InvalidHexLength
• InvalidRgbValue
• InvalidHslValue
• InvalidHsvValue
• InvalidCmykValue
• InvalidMinecraftCode

Examples

Basic Color Conversion

use chroma_forge::Color;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let color = Color::from_hex("#FF5733")?;

    println!("Original: {}", color.to_hex());
    println!("RGB: {}", color.to_rgb());
    println!("HSL: {}", color.to_hsl());
    println!("HSV: {}", color.to_hsv());
    println!("CMYK: {}", color.to_cmyk());

    Ok(())
}

Minecraft Integration

use chroma_forge::Color;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Parse various Minecraft color formats
    let colors = [
        Color::from_minecraft_code("§c")?,           // Legacy red
        Color::from_minecraft_code("&#FF5733")?,     // Modern hex
        Color::from_minecraft_code("&x&F&F&5&7&3&3")?, // Alt hex
    ];

    for color in colors {
        println!("Color: {} -> MC: {}",
                color.to_hex(),
                color.to_minecraft_code());
    }

    Ok(())
}

Color Analysis

use chroma_forge::Color;

fn analyze_color(hex: &str) -> Result<(), Box<dyn std::error::Error>> {
    let color = Color::from_hex(hex)?;

    println!("Analyzing color: {}", color.to_hex());
    println!("Luminance: {:.2}", color.luminance());
    println!("Is dark: {}", color.is_dark());
    println!("Best text color: {}", color.contrasting_text_color().to_hex());
    println!("Darker version: {}", color.darken(20.0).to_hex());
    println!("Lighter version: {}", color.lighten(20.0).to_hex());

    Ok(())
}

Performance

chroma-forge is designed for performance with:

• Zero-copy string parsing where possible
• Efficient mathematical operations
• Minimal memory allocations
• No external dependencies

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. Make sure to:

1. Add tests for new functionality
2. Update documentation
3. Follow Rust best practices
4. Ensure all tests pass

License

This project is licensed under MIT License

Changelog

1.0.0

• Initial release
• RGB, Hex, HSL, HSV, CMYK support
• Minecraft color code support
• Color manipulation utilities
• Comprehensive error handling
• Full test coverage