Module color

dotmax

Module color 

Source
Expand description

Color conversion and escape code generation for terminal output.

This module provides RGB to ANSI color conversion functions that enable colored output across terminals with varying capability levels (16-color, 256-color, or 24-bit true color).

§Overview

Terminal color support varies widely:

  • ANSI 16: Basic 16-color palette (legacy terminals)
  • ANSI 256: Extended 256-color palette (most modern terminals)
  • True Color: Full 24-bit RGB (modern terminals like iTerm2, Windows Terminal)

This module converts any RGB color to the appropriate format based on detected terminal capabilities.

§Examples

§Basic RGB to ANSI Conversion

use dotmax::color::convert::{rgb_to_ansi256, rgb_to_ansi16};

// Convert bright red to ANSI 256 palette index
let ansi256 = rgb_to_ansi256(255, 0, 0);
assert_eq!(ansi256, 196);  // Bright red in color cube

// Convert to basic 16-color palette
let ansi16 = rgb_to_ansi16(255, 0, 0);
assert_eq!(ansi16, 9);  // Bright red

§Generating Escape Codes

use dotmax::color::convert::{rgb_to_truecolor_escape, ansi256_fg_escape, color_reset};

// True color escape code
let escape = rgb_to_truecolor_escape(255, 128, 0);
assert_eq!(escape, "\x1b[38;2;255;128;0m");

// ANSI 256 escape code
let escape = ansi256_fg_escape(196);
assert_eq!(escape, "\x1b[38;5;196m");

// Reset colors
assert_eq!(color_reset(), "\x1b[0m");

§Smart Conversion Based on Terminal Capability

use dotmax::color::convert::rgb_to_terminal_color;
use dotmax::ColorCapability;

let r = 255;
let g = 128;
let b = 0;

// True color terminal - uses full RGB
let escape = rgb_to_terminal_color(r, g, b, ColorCapability::TrueColor);
assert_eq!(escape, "\x1b[38;2;255;128;0m");

// 256-color terminal - converts to nearest palette color
let escape = rgb_to_terminal_color(r, g, b, ColorCapability::Ansi256);
assert!(escape.starts_with("\x1b[38;5;"));

// Monochrome terminal - returns empty string
let escape = rgb_to_terminal_color(r, g, b, ColorCapability::Monochrome);
assert_eq!(escape, "");

§Performance

All conversion functions are optimized for performance:

  • rgb_to_ansi256: <100ns per conversion
  • rgb_to_ansi16: <50ns per conversion
  • Escape code generation: <50ns per call

§ANSI 256 Palette Structure

The ANSI 256 palette is organized as follows:

  • Indices 0-15: Standard 16 ANSI colors (system colors)
  • Indices 16-231: 6×6×6 color cube (216 colors)
  • Indices 232-255: 24-step grayscale ramp

See convert module for detailed documentation.

Re-exports§

pub use convert::ansi16_bg_escape;
pub use convert::ansi16_fg_escape;
pub use convert::ansi256_bg_escape;
pub use convert::ansi256_fg_escape;
pub use convert::color_reset;
pub use convert::rgb_to_ansi16;
pub use convert::rgb_to_ansi256;
pub use convert::rgb_to_terminal_color;
pub use convert::rgb_to_truecolor_bg_escape;
pub use convert::rgb_to_truecolor_escape;
pub use schemes::blue_purple;
pub use schemes::cyan_magenta;
pub use schemes::get_scheme;
pub use schemes::grayscale;
pub use schemes::green_yellow;
pub use schemes::heat_map;
pub use schemes::list_schemes;
pub use schemes::monochrome;
pub use schemes::rainbow;
pub use schemes::ColorScheme;
pub use scheme_builder::ColorSchemeBuilder;
pub use apply::apply_color_scheme;
pub use apply::apply_colors_to_grid;

Modules§

apply
Color scheme application to intensity buffers.
convert
RGB to ANSI color conversion algorithms.
scheme_builder
Builder pattern for creating custom color schemes.
schemes
Predefined color schemes for intensity-to-color mapping.