feat: add RGB/HSV color conversion

[AliAlimohammadi]

Description

This PR adds a new module for converting between RGB and HSV color representations.

Features Added:

• hsv_to_rgb: Convert HSV (Hue, Saturation, Value) to RGB (Red, Green, Blue)
• rgb_to_hsv: Convert RGB to HSV
• Rgb and Hsv structs for type-safe color representation
• Custom error types for validation failures
• Comprehensive test coverage (12 unit tests)

Type of Change

• New algorithm/data structure
• Documentation
• Tests

Testing

All tests pass:

cargo test rgb_hsv_conversion

Results:

• 12 unit tests passed
• Test coverage includes:
  • Basic color conversions (black, white, red, green, blue, yellow, magenta)
  • Intermediate color values
  • Input validation (hue, saturation, value ranges)
  • Round-trip conversions (HSV → RGB → HSV)
  • Approximate equality for floating-point comparisons
  • Edge cases

Algorithm Complexity

• Time Complexity: $O(1)$ - constant time operations
• Space Complexity: $O(1)$ - fixed size structures

Implementation Details

HSV to RGB

• Uses standard HSV to RGB conversion algorithm
• Divides hue into 6 sectors (60° each)
• Calculates RGB components based on chroma, hue section, and match value
• Returns Result type for error handling

RGB to HSV

• Normalizes RGB values to [0, 1] range
• Calculates value as maximum RGB component
• Computes saturation from chroma and value
• Determines hue based on which RGB component is maximum
• Returns Result type for error handling

Error Handling

Custom ColorError enum with variants:

• InvalidHue(f64) - Hue not in [0, 360]
• InvalidSaturation(f64) - Saturation not in [0, 1]
• InvalidValue(f64) - Value not in [0, 1]

Approximate Equality

The Hsv::approximately_equal method uses tolerance values to compare floating-point HSV values:

• Hue: 0.2 degrees
• Saturation: 0.002
• Value: 0.002

This accounts for rounding errors in round-trip conversions.

References

• https://en.wikipedia.org/wiki/RGB_color_model
• https://en.wikipedia.org/wiki/HSL_and_HSV
• https://www.rapidtables.com/convert/color/hsv-to-rgb.html

Checklist

• Code follows Rust idioms and best practices
• Self-documenting code with comprehensive doc comments
• All functions have doc comments
• Tests cover normal cases, edge cases, and error cases
• Error types implement Display and Error traits
• Code compiles without warnings
• All tests pass
• Proper use of type-safe structs (Rgb, Hsv)
• Input validation in constructors

Example Usage

use rgb_hsv_conversion::{hsv_to_rgb, rgb_to_hsv, Rgb, Hsv};

// Convert HSV to RGB
let rgb = hsv_to_rgb(240.0, 1.0, 1.0).unwrap();
assert_eq!(rgb, Rgb::new(0, 0, 255)); // Blue

// Convert RGB to HSV
let hsv = rgb_to_hsv(255, 0, 0).unwrap();
assert!(Hsv::new(0.0, 1.0, 1.0).unwrap().approximately_equal(&hsv)); // Red

// Round-trip conversion
let original = Hsv::new(180.0, 0.5, 0.5).unwrap();
let rgb = hsv_to_rgb(180.0, 0.5, 0.5).unwrap();
let converted = rgb_to_hsv(rgb.red, rgb.green, rgb.blue).unwrap();
assert!(original.approximately_equal(&converted));

Additional Notes

• The module uses f64 for HSV values to maintain precision
• RGB values are u8 (0-255) as per standard
• All input values are validated
• Round-trip conversions maintain accuracy within tolerance

[AliAlimohammadi]

@siriak, this is ready to be merged.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 96.15385% with 9 lines in your changes missing coverage. Please review.
✅ Project coverage is 95.96%. Comparing base (47ea8bd) to head (0ccc38e).
⚠️ Report is 25 commits behind head on master.

Files with missing lines	Patch %	Lines
src/conversions/rgb_hsv_conversion.rs	96.15%	9 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #995      +/-   ##
==========================================
- Coverage   95.96%   95.96%   -0.01%     
==========================================
  Files         364      365       +1     
  Lines       24810    25044     +234     
==========================================
+ Hits        23810    24033     +223     
- Misses       1000     1011      +11     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.