MunsellSpace 🎨

High-precision sRGB to Munsell color space conversion library with ISCC-NBS color naming system support.

Overview

MunsellSpace is a high-performance Rust library for converting sRGB colors to Munsell color notation and ISCC-NBS color names. This implementation is based on the mathematical algorithms from the Python Colour Science library, providing accurate color space transformations with comprehensive thread safety support.

✨ Features

• High-Precision Conversion: Multiple mathematical conversion algorithms with configurable illuminants
• ISCC-NBS Classification: Convert colors to standardized ISCC-NBS color names (267 categories)
• Multiple Illuminants: Support for C, D65, and F7 illuminants with chromatic adaptation
• Thread-Safe Architecture: Full Send + Sync support for concurrent processing
• Comprehensive API: Support for RGB, Lab, and hex color input formats
• Performance Optimized: Efficient caching and parallel processing capabilities
• Scientific Accuracy: Based on established color science algorithms and standards

🚀 Quick Start

Installation

Add to your Cargo.toml:

[dependencies]
munsellspace = "1.0"

Basic Usage

use munsellspace::{MunsellConverter, IsccNbsClassifier};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create converter for Munsell notation
    let converter = MunsellConverter::new()?;
    
    // Convert RGB to Munsell
    let munsell = converter.srgb_to_munsell([255, 0, 0])?;
    println!("Pure red: {}", munsell); // Output: 7.9R 5.2/20.5
    
    // Create ISCC-NBS classifier
    let classifier = IsccNbsClassifier::new()?;
    
    // Classify color to ISCC-NBS name
    let color_name = classifier.classify_rgb([255, 0, 0])?;
    println!("Color name: {:?}", color_name); // Output: vivid red
    
    Ok(())
}

📊 Color Systems

Munsell Color System

The Munsell color system describes colors using three perceptually uniform dimensions:

• Hue: Color family (R, YR, Y, GY, G, BG, B, PB, P, RP)
• Value: Lightness from 0 (black) to 10 (white)
• Chroma: Saturation from 0 (neutral) to variable maximum

Notation Format: HUE VALUE/CHROMA (e.g., 5R 4.0/14.0)

ISCC-NBS Color System

The Inter-Society Color Council - National Bureau of Standards (ISCC-NBS) system provides standardized color names for 267 distinct color categories. Each color is defined by:

• Numerical identifier (1-267)
• Descriptive name (e.g., "vivid red", "light grayish blue")
• Polygonal region in Munsell color space

Color Vocabulary Reference

The library supports three color naming systems, each with increasing specificity:

Standard ISCC-NBS Base Colors (29 names)

These are the official ISCC-NBS color name components, organized by hue progression:

Extended Color Names (MunsellSpace additions)

These provide more recognizable alternatives for compound ISCC-NBS names:

Use BaseColorSet::Extended to get these names instead of the compound forms.

Semantic Overlays (Centore 2020)

30 color names derived from fabric samples, providing natural language color terms. Sorted by hue progression:

Color Modifiers

Modifiers combine with base colors to form the 267 ISCC-NBS categories:

Example outputs: "vivid red", "pale yellow", "dark grayish blue", "pinkish white"

🔬 Technical Details

Mathematical Conversion Pipeline

The library implements a sophisticated color conversion pipeline:

1. sRGB → Linear RGB: Gamma correction removal
2. Linear RGB → XYZ: Color space transformation (ITU-R BT.709)
3. XYZ → xyY: Chromaticity and luminance separation
4. Chromatic Adaptation: Optional adaptation between illuminants
5. xyY → Munsell: Mathematical transformation to Munsell notation
6. Munsell → ISCC-NBS: Geometric point-in-polygon classification

Supported Illuminants

• C: Traditional daylight (used in original Munsell specifications)
• D65: Standard daylight (sRGB native illuminant)
• F7: Fluorescent light source

Chromatic Adaptation Methods

• XYZ Scaling: Simple von Kries transformation
• Bradford: More sophisticated adaptation matrix
• CAT02: Advanced chromatic adaptation transform

🔒 Thread Safety

All public types implement Send + Sync for safe concurrent usage:

use munsellspace::{MunsellConverter, IsccNbsClassifier};
use std::sync::Arc;
use std::thread;

let converter = Arc::new(MunsellConverter::new()?);
let classifier = Arc::new(IsccNbsClassifier::new()?);

let mut handles = vec![];

for thread_id in 0..4 {
    let conv = Arc::clone(&converter);
    let class = Arc::clone(&classifier);
    
    let handle = thread::spawn(move || {
        let munsell = conv.srgb_to_munsell([255, 0, 0])?;
        let color_name = class.classify_rgb([255, 0, 0])?;
        println!("Thread {}: {} -> {:?}", thread_id, munsell, color_name);
        Ok::<(), Box<dyn std::error::Error + Send + Sync>>(())
    });
    
    handles.push(handle);
}

for handle in handles {
    handle.join().unwrap()?;
}

📈 Performance

• Single conversion: <1ms per color
• Batch processing: 4,000+ colors/second
• Memory usage: <100MB for complete reference dataset
• Caching: Automatic result caching for repeated conversions

📚 API Documentation

For detailed API documentation, visit docs.rs/munsellspace.

Key modules:

• converter: Core Munsell conversion functionality
• iscc: ISCC-NBS classification system
• types: Color type definitions and validation
• illuminants: Illuminant definitions and adaptation
• mathematical: Mathematical conversion algorithms

🛠️ Development

Building from Source

# Clone repository
git clone https://github.com/chrisgve/MunsellSpace.git
cd MunsellSpace

# Build library
cargo build --release

# Run tests
cargo test

# Run benchmarks
cargo bench

# Generate documentation
cargo doc --open

Testing

# Run all tests
cargo test

# Run with output
cargo test -- --nocapture

# Run specific test
cargo test test_name

# Run benchmarks
cargo bench

🙏 Acknowledgments & Credits

This library builds upon decades of color science research and open-source contributions:

Core Algorithms

• Python Colour Science: This implementation is based on the mathematical algorithms from the Python colour-science library, specifically the Munsell color notation conversion functions. We are deeply grateful for their comprehensive and well-documented implementation.
• Paul Centore's Munsell Research: This library incorporates methodology from Dr. Paul Centore's work on sRGB-to-Munsell conversion, including his chromatic adaptation techniques and validation datasets.

Scientific References

• Semantic Color Names: Centore, P. (2020). Beige, aqua, fuchsia, etc.: Definitions for some non-basic surface colour names. Journal of the International Colour Association, 25, 24-54. The 30 semantic color overlays in this library are derived from the convex polyhedra defined in this paper.
• Munsell Renotation Data: Based on the original Munsell renotation studies (1943) and subsequent refinements
• ISCC-NBS Method of Designating Colors: Kelly, K.L. & Judd, D.B. (1976). Color: Universal Language and Dictionary of Names
• CIE Standards: International Commission on Illumination specifications for color spaces and illuminants
• ITU-R BT.709: International standard for sRGB color space transformation

Data Sources

• Munsell Renotation Dataset: Original renotation data from the Munsell Color Science Laboratory
• ISCC-NBS Definitions: The 267 color categories and Munsell-space boundaries are derived from the Inter-Society Color Council (ISCC) and National Bureau of Standards (NBS) publications
• Reference RGB Values: Validated sRGB to Munsell mappings from multiple sources

Community

• The Rust community for excellent tooling and support
• Contributors to the color science field for their research and publications
• Open-source maintainers who make scientific computing accessible

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

📄 License

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

🔗 Links

• Repository: github.com/chrisgve/MunsellSpace
• Documentation: docs.rs/munsellspace
• Issue Tracker: GitHub Issues
• Python Colour Science: colour-science/colour
• Munsell Color System: munsell.com

MunsellSpace - High-precision color space conversion for Rust 🦀