abachrome 0.1.0 → 0.1.2

data/lib/abachrome/converter.rb

@@ -1,16 +1,53 @@
-# frozen_string_literal: true
+# Abachrome::Converter - Color space conversion registry and orchestration system
+#
+# This module provides the central registry and conversion orchestration for transforming colors
+# between different color spaces within the Abachrome library. It manages a registry of converter
+# classes that handle transformations between specific color space pairs (e.g., sRGB to OKLAB,
+# OKLCH to linear RGB) and provides the main conversion interface used throughout the library.
+#
+# Key features:
+# - Global registry for color space converter registration with automatic discovery
+# - Converter lookup and routing between source and target color spaces
+# - Automatic registration of all converter classes found in the Converters namespace
+# - Conversion orchestration that finds appropriate converters based on color model compatibility
+# - Support for multi-step conversions through intermediate color spaces when needed
+# - Integration with the ColorSpace system for proper color space identification
+#
+# The Converter system serves as the backbone for all color transformations in Abachrome,
+# enabling seamless conversion between any registered color spaces while maintaining the
+# precision and accuracy required for color science calculations. Converter classes follow
+# a naming convention (FromSpaceToSpace) for automatic registration and discovery.
 
 module Abachrome
   class Converter
     class << self
+      # Returns the registry hash used to store color space converters.
+      # 
+      # This method lazily initializes and returns the hash used internally to store
+      # converter mappings between different color spaces. This registry is a central
+      # repository that maps color space pairs to their appropriate conversion functions.
+      # 
+      # @return [Hash] The converter registry hash, mapping color space pairs to converter functions
       def registry
         @registry ||= {}
       end
 
+      # Register a converter class for transforming colors between two specific color spaces.
+      # 
+      # @param from_space [Symbol, String] The source color space identifier
+      # @param to_space [Symbol, String] The destination color space identifier
+      # @param converter_class [Class] The converter class that implements the transformation
+      # @return [Class] The registered converter class
       def register(from_space, to_space, converter_class)
         registry[[from_space.to_s, to_space.to_s]] = converter_class
       end
 
+      # Converts a color from its current color space to the specified target color space.
+      # 
+      # @param color [Abachrome::Color] The color to convert
+      # @param to_space_name [String, Symbol] The name of the target color space
+      # @return [Abachrome::Color] The color converted to the target color space
+      # @raise [RuntimeError] If no converter is found between the source and target color models
       def convert(color, to_space_name)
         to_space = ColorSpace.find(to_space_name)
         return color if color.color_space == to_space
@@ -23,7 +60,19 @@ module Abachrome
         converter.convert(color)
       end
 
-      # Automatically register all converters in the Converters namespace
+      # @api private
+      # @since 0.1.0
+      # @example
+      # converter = Abachrome::Converter.new
+      # converter.register_all_converters
+      # 
+      # Automatically registers all converter classes found in the Converters namespace.
+      # The method iterates through constants in the Converters module, identifies classes
+      # with naming pattern "FromSpaceToSpace" (e.g., LrgbToOklab), extracts the source
+      # and destination color spaces from the class name, and registers the converter
+      # class for the corresponding color space conversion.
+      # 
+      # @return [void]
       def register_all_converters
         Converters.constants.each do |const_name|
           const = Converters.const_get(const_name)
@@ -42,6 +91,11 @@ module Abachrome
 
       private
 
+      # Retrieves a converter function between two color spaces from the registry.
+      # 
+      # @param from_space_name [String, Symbol] The source color space name
+      # @param to_space_name [String, Symbol] The target color space name
+      # @return [Proc, nil] The conversion function if registered, or nil if no converter exists for the specified color spaces
       def find_converter(from_space_name, to_space_name)
         registry[[from_space_name.to_s, to_space_name.to_s]]
       end

data/lib/abachrome/converters/base.rb

@@ -1,39 +1,100 @@
-# frozen_string_literal: true
+# Abachrome::Converters::Base - Abstract base class for color space converters
+#
+# This class provides the foundation for implementing color space conversion functionality
+# within the Abachrome library. It defines the interface that all converter classes must
+# implement and provides common validation and utility methods for color transformations.
+#
+# Key features:
+# - Abstract conversion interface requiring subclasses to implement #convert method
+# - Color model validation to ensure proper conversion compatibility
+# - Converter registration and lookup system for managing conversion mappings
+# - Source and target color space compatibility checking
+# - Base functionality for building specific converter implementations
+#
+# All converter classes in the Abachrome system inherit from this base class and implement
+# the specific mathematical transformations needed to convert colors between different
+# color spaces such as sRGB, OKLAB, OKLCH, and linear RGB. The class follows a naming
+# convention pattern (FromSpaceToSpace) for automatic registration and discovery.
 
 module Abachrome
   module Converters
     class Base
       attr_reader :from_space, :to_space
 
+      # Initialize a new converter between two color spaces.
+      # 
+      # @param from_space [Abachrome::ColorSpace] The source color space to convert from
+      # @param to_space [Abachrome::ColorSpace] The target color space to convert to
+      # @return [Abachrome::Converters::Base] A new converter instance
       def initialize(from_space, to_space)
         @from_space = from_space
         @to_space = to_space
       end
 
+      # Converts a color from one color space to another.
+      # 
+      # @abstract This is an abstract method that must be implemented by subclasses.
+      # @param color [Abachrome::Color] The color to convert
+      # @return [Abachrome::Color] The converted color
+      # @raise [NotImplementedError] If the subclass doesn't implement this method
       def convert(color)
         raise NotImplementedError, "Subclasses must implement #convert"
       end
 
+      # Validates that a color uses the expected color model.
+      # 
+      # @param color [Abachrome::Color] The color object to check
+      # @param model [Symbol, String] The expected color model
+      # @raise [RuntimeError] If the color's model doesn't match the expected model
+      # @return [nil] If the color's model matches the expected model
       def self.raise_unless(color, model)
         return if color.color_space.color_model == model
 
         raise "#{color} is #{color.color_space.color_model}), expecting #{model}"
       end
 
+      # Determines if the converter can handle the given color.
+      # 
+      # This method checks if the color's current color space matches
+      # the converter's source color space.
+      # 
+      # @param color [Abachrome::Color] The color to check
+      # @return [Boolean] true if the converter can convert from the color's current color space,
+      # false otherwise
       def can_convert?(color)
         color.color_space == from_space
       end
 
+      # Register a converter class for transforming colors between two specific color spaces.
+      # 
+      # @param from_space_id [Symbol] The identifier of the source color space
+      # @param to_space_id [Symbol] The identifier of the destination color space
+      # @param converter_class [Class] The converter class that handles the transformation
+      # @return [void]
       def self.register(from_space_id, to_space_id, converter_class)
         @converters ||= {}
         @converters[[from_space_id, to_space_id]] = converter_class
       end
 
+      # Find a converter for converting between color spaces.
+      # 
+      # @param from_space_id [Symbol, String] The identifier of the source color space
+      # @param to_space_id [Symbol, String] The identifier of the destination color space
+      # @return [Converter, nil] The converter instance for the specified color spaces, or nil if no converter is found
       def self.find_converter(from_space_id, to_space_id)
         @converters ||= {}
         @converters[[from_space_id, to_space_id]]
       end
 
+      # Converts a color from its current color space to a target color space.
+      # 
+      # This method finds the appropriate converter class for the given source and
+      # target color spaces and performs the conversion.
+      # 
+      # @param color [Abachrome::Color] The color to convert
+      # @param to_space [Abachrome::ColorSpace] The target color space to convert to
+      # @return [Abachrome::Color] The converted color in the target color space
+      # @raise [ConversionError] If no converter is found for the given color spaces
       def self.convert(color, to_space)
         converter_class = find_converter(color.color_space.id, to_space.id)
         unless converter_class
@@ -47,6 +108,12 @@ module Abachrome
 
       private
 
+      # Validates if a color can be converted from its current color space.
+      # Raises an ArgumentError if the color's space doesn't match the expected source space.
+      # 
+      # @param color [Abachrome::Color] The color object to validate
+      # @raise [ArgumentError] If the color cannot be converted from its current color space
+      # @return [nil] Returns nil if the color is valid for conversion
       def validate_color!(color)
         return if can_convert?(color)
 
@@ -54,4 +121,4 @@ module Abachrome
       end
     end
   end
-end
+end

data/lib/abachrome/converters/lms_to_lrgb.rb

@@ -0,0 +1,36 @@
+module Abachrome
+  module Converters
+    class LmsToLrgb < Abachrome::Converters::Base
+      # Converts a color from LMS color space to linear RGB color space.
+      # 
+      # This method implements the final part of the OKLAB to linear RGB transformation,
+      # converting LMS (Long, Medium, Short) coordinates to linear RGB coordinates
+      # using the standard transformation matrix. The LMS color space represents
+      # the response of the three types of cone cells in the human eye.
+      # 
+      # @param lms_color [Abachrome::Color] The color in LMS color space
+      # @raise [ArgumentError] If the input color is not in LMS color space
+      # @return [Abachrome::Color] The resulting color in linear RGB color space with
+      # the same alpha as the input color
+      def self.convert(lms_color)
+        raise_unless lms_color, :lms
+
+        l, m, s = lms_color.coordinates.map { |_| AbcDecimal(_) }
+
+        r = (l * AD("4.07674166134799")) +
+            (m * AD("-3.307711590408193")) +
+            (s * AD("0.230969928729428"))
+        g = (l * AD("-1.2684380040921763")) +
+            (m * AD("2.6097574006633715")) +
+            (s * AD("-0.3413193963102197"))
+        b = (l * AD("-0.004196086541837188")) +
+            (m * AD("-0.7034186144594493")) +
+            (s * AD("1.7076147009309444"))
+
+        output_coords = [r, g, b].map { |it| [it, 0].max }
+
+        Color.new(ColorSpace.find(:lrgb), output_coords, lms_color.alpha)
+      end
+    end
+  end
+end

data/lib/abachrome/converters/lms_to_srgb.rb

@@ -0,0 +1,23 @@
+module Abachrome
+  module Converters
+    class LmsToSrgb < Abachrome::Converters::Base
+      # Converts a color from LMS color space to sRGB color space.
+      # 
+      # This method implements a two-step conversion process:
+      # 1. First converts from LMS to linear RGB using the standard transformation matrix
+      # 2. Then converts from linear RGB to sRGB by applying gamma correction
+      # 
+      # @param lms_color [Abachrome::Color] The color in LMS color space
+      # @raise [ArgumentError] If the input color is not in LMS color space
+      # @return [Abachrome::Color] The resulting color in sRGB color space with
+      # the same alpha as the input color
+      def self.convert(lms_color)
+        # First convert LMS to linear RGB
+        lrgb_color = LmsToLrgb.convert(lms_color)
+        
+        # Then convert linear RGB to sRGB
+        LrgbToSrgb.convert(lrgb_color)
+      end
+    end
+  end
+end

data/lib/abachrome/converters/lms_to_xyz.rb

@@ -0,0 +1,30 @@
+module Abachrome
+  module Converters
+    class LmsToXyz < Abachrome::Converters::Base
+      # Converts a color from LMS color space to XYZ color space.
+      # 
+      # This method implements the LMS to XYZ transformation using the standard
+      # transformation matrix. The LMS color space represents the response of
+      # the three types of cone cells in the human eye (Long, Medium, Short),
+      # while XYZ is the CIE 1931 color space that forms the basis for most
+      # other color space definitions.
+      # 
+      # @param lms_color [Abachrome::Color] The color in LMS color space
+      # @raise [ArgumentError] If the input color is not in LMS color space
+      # @return [Abachrome::Color] The resulting color in XYZ color space with
+      # the same alpha as the input color
+      def self.convert(lms_color)
+        raise_unless lms_color, :lms
+
+        l, m, s = lms_color.coordinates.map { |_| AbcDecimal(_) }
+
+        # LMS to XYZ transformation matrix
+        x = (l * AD("1.86006661")) - (m * AD("1.12948190")) + (s * AD("0.21989740"))
+        y = (l * AD("0.36122292")) + (m * AD("0.63881308")) - (s * AD("0.00000000"))
+        z = (l * AD("0.00000000")) - (m * AD("0.00000000")) + (s * AD("1.08906362"))
+
+        Color.new(ColorSpace.find(:xyz), [x, y, z], lms_color.alpha)
+      end
+    end
+  end
+end

data/lib/abachrome/converters/lrgb_to_oklab.rb

@@ -1,8 +1,34 @@
-# frozen_string_literal: true
+# Abachrome::Converters::LrgbToOklab - Linear RGB to OKLAB color space converter
+#
+# This converter transforms colors from the linear RGB (LRGB) color space to the OKLAB color space
+# using the standard OKLAB transformation matrices. The conversion process applies a series of
+# matrix transformations and non-linear operations to accurately map linear RGB coordinates to
+# the perceptually uniform OKLAB color space.
+#
+# Key features:
+# - Implements the official OKLAB transformation algorithm with high-precision matrices
+# - Converts linear RGB values through intermediate LMS color space representation
+# - Applies cube root transformation for perceptual uniformity in the OKLAB space
+# - Maintains alpha channel transparency values during conversion
+# - Uses AbcDecimal arithmetic for precise color science calculations
+# - Validates input color space to ensure proper linear RGB source data
+#
+# The OKLAB color space provides better perceptual uniformity compared to traditional RGB spaces,
+# making it ideal for color manipulation operations like blending, lightness adjustments, and
+# gamut mapping where human visual perception accuracy is important.
 
 module Abachrome
   module Converters
     class LrgbToOklab < Abachrome::Converters::Base
+      # Converts a color from linear RGB (LRGB) color space to OKLAB color space.
+      # 
+      # This conversion applies a matrix transformation to the linear RGB values,
+      # followed by a non-linear transformation, then another matrix transformation
+      # to produce OKLAB coordinates.
+      # 
+      # @param rgb_color [Abachrome::Color] A color in linear RGB (LRGB) color space
+      # @raise [ArgumentError] If the provided color is not in LRGB color space
+      # @return [Abachrome::Color] The converted color in OKLAB color space with the same alpha value as the input
       def self.convert(rgb_color)
         raise_unless rgb_color, :lrgb
 
@@ -24,4 +50,4 @@ module Abachrome
       end
     end
   end
-end
+end

data/lib/abachrome/converters/lrgb_to_srgb.rb

@@ -1,8 +1,25 @@
-# frozen_string_literal: true
+# Abachrome::Converters::LrgbToSrgb - Linear RGB to sRGB color space converter
+#
+# This converter transforms colors from the linear RGB (LRGB) color space to the standard RGB (sRGB) color space by applying gamma correction. The conversion process applies the sRGB transfer function which uses different formulas for small and large values to match the non-linear response characteristics of typical display devices.
+#
+# Key features:
+# - Implements the standard sRGB gamma correction algorithm with precise threshold handling
+# - Converts linear RGB values to gamma-corrected sRGB values for proper display representation
+# - Applies different transformation functions based on value magnitude (linear vs power function)
+# - Maintains alpha channel transparency values during conversion
+# - Uses AbcDecimal arithmetic for precise color science calculations
+# - Validates input color space to ensure proper linear RGB source data
+#
+# The sRGB color space is the standard RGB color space for web content and most consumer displays, providing gamma correction that better matches human visual perception and display device characteristics compared to linear RGB values.
 
 module Abachrome
   module Converters
     class LrgbToSrgb < Abachrome::Converters::Base
+      # Converts a color from linear RGB to sRGB color space.
+      # 
+      # @param lrgb_color [Abachrome::Color] The color in linear RGB color space to convert
+      # @return [Abachrome::Color] A new Color object in sRGB color space with the converted coordinates
+      # @raise [TypeError] If the provided color is not in linear RGB color space
       def self.convert(lrgb_color)
         raise_unless lrgb_color, :lrgb
         r, g, b = lrgb_color.coordinates.map { |c| to_srgb(AbcDecimal(c)) }
@@ -16,6 +33,14 @@ module Abachrome
         )
       end
 
+      # Converts a linear RGB value to standard RGB color space (sRGB) value.
+      # 
+      # This method implements the standard linearization function used in the sRGB color space.
+      # For small values (≤ 0.0031308), a simple linear transformation is applied.
+      # For larger values, a power function with gamma correction is used.
+      # 
+      # @param v [AbcDecimal] The linear RGB value to convert
+      # @return [AbcDecimal] The corresponding sRGB value, preserving the sign of the input
       def self.to_srgb(v)
         v_abs = v.abs
         v_sign = v.negative? ? -1 : 1
@@ -27,4 +52,4 @@ module Abachrome
       end
     end
   end
-end
+end

data/lib/abachrome/converters/lrgb_to_xyz.rb

@@ -0,0 +1,29 @@
+module Abachrome
+  module Converters
+    class LrgbToXyz < Abachrome::Converters::Base
+      # Converts a color from linear RGB color space to XYZ color space.
+      # 
+      # This method implements the linear RGB to XYZ transformation using the standard
+      # transformation matrix for the sRGB color space with D65 white point. The XYZ
+      # color space is the CIE 1931 color space that forms the basis for most other
+      # color space definitions and serves as a device-independent reference.
+      # 
+      # @param lrgb_color [Abachrome::Color] The color in linear RGB color space
+      # @raise [ArgumentError] If the input color is not in linear RGB color space
+      # @return [Abachrome::Color] The resulting color in XYZ color space with
+      # the same alpha as the input color
+      def self.convert(lrgb_color)
+        raise_unless lrgb_color, :lrgb
+
+        r, g, b = lrgb_color.coordinates.map { |_| AbcDecimal(_) }
+
+        # Linear RGB to XYZ transformation matrix (sRGB/D65)
+        x = (r * AD("0.4124564")) + (g * AD("0.3575761")) + (b * AD("0.1804375"))
+        y = (r * AD("0.2126729")) + (g * AD("0.7151522")) + (b * AD("0.0721750"))
+        z = (r * AD("0.0193339")) + (g * AD("0.1191920")) + (b * AD("0.9503041"))
+
+        Color.new(ColorSpace.find(:xyz), [x, y, z], lrgb_color.alpha)
+      end
+    end
+  end
+end

data/lib/abachrome/converters/oklab_to_lms.rb

@@ -0,0 +1,41 @@
+module Abachrome
+  module Converters
+    class OklabToLms < Abachrome::Converters::Base
+      # Converts a color from OKLAB color space to LMS color space.
+      # 
+      # This method implements the first part of the OKLAB to linear RGB transformation,
+      # converting OKLAB coordinates to the intermediate LMS (Long, Medium, Short) color space
+      # which represents the response of the three types of cone cells in the human eye.
+      # 
+      # @param oklab_color [Abachrome::Color] The color in OKLAB color space
+      # @raise [ArgumentError] If the input color is not in OKLAB color space
+      # @return [Abachrome::Color] The resulting color in LMS color space with
+      # the same alpha as the input color
+      def self.convert(oklab_color)
+        raise_unless oklab_color, :oklab
+
+        l, a, b = oklab_color.coordinates.map { |_| AbcDecimal(_) }
+
+        l_ = AbcDecimal((l ) +
+                        (AD("0.39633779217376785678") * a) +
+                        (AD("0.21580375806075880339") * b))
+
+        m_ = AbcDecimal((l) -
+                        (a * AD("-0.1055613423236563494")) +
+                        (b * AD("-0.063854174771705903402")))
+        
+        s_ = AbcDecimal((l) -
+                        (a * AD("-0.089484182094965759684")) +
+                        (b * AD("-1.2914855378640917399")))
+
+        # Apply cubic operation to convert from L'M'S' to LMS
+        l_lms = AbcDecimal(l_)**3
+        m_lms = AbcDecimal(m_)**3
+        s_lms = AbcDecimal(s_)**3
+
+        Color.new(ColorSpace.find(:lms), [l_lms, m_lms, s_lms], oklab_color.alpha)
+      end
+    end
+  end
+end
+

data/lib/abachrome/converters/oklab_to_lrgb.rb

@@ -1,39 +1,66 @@
-# frozen_string_literal: true
+# Abachrome::Converters::OklabToLrgb - OKLAB to Linear RGB color space converter
+#
+# This converter transforms colors from the OKLAB color space to the linear RGB (LRGB) color space
+# using the standard OKLAB transformation matrices. The conversion process first transforms
+# OKLAB coordinates to the intermediate LMS (Long, Medium, Short) color space, then applies
+# another matrix transformation to convert LMS coordinates to linear RGB coordinates.
+#
+# Key features:
+# - Implements the official OKLAB inverse transformation algorithm with high-precision matrices
+# - Converts OKLAB coordinates through intermediate LMS color space representation
+# - Applies cubic transformation for perceptual uniformity in the OKLAB space
+# - Maintains alpha channel transparency values during conversion
+# - Uses AbcDecimal arithmetic for precise color science calculations
+# - Validates input color space to ensure proper OKLAB source data
+#
+# The linear RGB color space provides a linear relationship between stored numeric values and
+# actual light intensity, making it essential for accurate color calculations and serving as
+# an intermediate color space for many color transformations, particularly when converting
+# between different color models or preparing colors for display on standard monitors.
 
 module Abachrome
   module Converters
     class OklabToLrgb < Abachrome::Converters::Base
+      # Converts a color from OKLAB color space to linear RGB (LRGB) color space.
+      #
+      # This method performs a two-step conversion:
+      # 1. OKLAB to LMS (cone response space)
+      # 2. LMS to LRGB (linear RGB)
+      #
+      # @param oklab_color [Abachrome::Color] The color in OKLAB color space
+      # @raise [ArgumentError] If the input color is not in OKLAB color space
+      # @return [Abachrome::Color] The resulting color in linear RGB color space with
+      # the same alpha as the input color
       def self.convert(oklab_color)
         raise_unless oklab_color, :oklab
 
-        l, a, b = oklab_color.coordinates.map { |_| AbcDecimal(_) }
-
-        l_ = AbcDecimal((l * AD("0.99999999845051981432")) +
-                        (AD("0.39633779217376785678") * a) +
-                        (AD("0.21580375806075880339") * b))
-
-        m_ = AbcDecimal((l * AD("1.0000000088817607767")) -
-                        (a * AD("0.1055613423236563494")) -
-                        (b * AD("0.063854174771705903402")))
-        s_ = AbcDecimal((l * AD("1.000000054672410917")) -
-                        (a * AD("0.089484182094965759684")) -
-                        (b * AD("1.2914855378640917399")))
-
-        l = AbcDecimal(l_)**3
-        m = AbcDecimal(m_)**3
-        s = AbcDecimal(s_)**3
-
-        r =  (l * AD("4.07674166134799")) -
-             (m * AD("3.307711590408193")) +
-             (s * AD("0.230969928729428"))
-        g =  (l * AD("-1.2684380040921763")) +
-             (m * AD("2.6097574006633715")) -
-             (s * AD("0.3413193963102197"))
-        b =  (l * AD("-0.004196086541837188")) -
-             (m * AD("0.7034186144594493")) +
-             (s * AD("1.7076147009309444"))
-
-        output_coords = [r, g, b].map { |it| [it, 0].max }
+        l_ok, a_ok, b_ok = oklab_color.coordinates.map { |_| AbcDecimal(_) }
+
+        # Step 1: OKLAB to L'M'S' (cone responses, non-linear)
+        # These are the M_lms_prime_from_oklab matrix operations.
+        l_prime = AbcDecimal(l_ok + (AD("0.39633779217376785678") * a_ok) + (AD("0.21580375806075880339") * b_ok))
+        m_prime = AbcDecimal(l_ok - (a_ok * AD("0.1055613423236563494")) - (b_ok * AD("0.063854174771705903402"))) # Note: original OklabToLms had + (b * AD("-0.063..."))
+        s_prime = AbcDecimal(l_ok - (a_ok * AD("0.089484182094965759684")) - (b_ok * AD("1.2914855378640917399"))) # Note: original OklabToLms had + (b * AD("-1.291..."))
+
+
+        # Step 2: L'M'S' to LMS (cubing)
+        l_lms = l_prime**3
+        m_lms = m_prime**3
+        s_lms = s_prime**3
+
+        # Step 3: LMS to LRGB
+        # Using matrix M_lrgb_from_lms (OKLAB specific)
+        r_lrgb = (l_lms * AD("4.07674166134799"))   + (m_lms * AD("-3.307711590408193")) + (s_lms * AD("0.230969928729428"))
+        g_lrgb = (l_lms * AD("-1.2684380040921763")) + (m_lms * AD("2.6097574006633715")) + (s_lms * AD("-0.3413193963102197"))
+        b_lrgb = (l_lms * AD("-0.004196086541837188"))+ (m_lms * AD("-0.7034186144594493")) + (s_lms * AD("1.7076147009309444"))
+
+        # Clamp LRGB values to be non-negative (as done in LmsToLrgb.rb)
+        # It's also common to clamp to [0, 1] range after conversion from a wider gamut space
+        # For LRGB, often just ensuring non-negative is done, and further clamping happens
+        # when converting to sRGB or other display spaces.
+        # Here, we'll ensure non-negative as per LmsToLrgb.
+        output_coords = [r_lrgb, g_lrgb, b_lrgb].map { |it| [it, AD(0)].max }
+
 
         Color.new(ColorSpace.find(:lrgb), output_coords, oklab_color.alpha)
       end

data/lib/abachrome/converters/oklab_to_oklch.rb

@@ -1,8 +1,37 @@
-# frozen_string_literal: true
+# Abachrome::Converters::OklabToOklch - OKLAB to OKLCH color space converter
+#
+# This converter transforms colors from the OKLAB color space to the OKLCH color space
+# using cylindrical coordinate conversion. The transformation converts the rectangular
+# coordinates (L, a, b) to cylindrical coordinates (L, C, h) where lightness remains
+# unchanged, chroma is calculated as the Euclidean distance in the a-b plane, and hue
+# is calculated as the angle in the a-b plane expressed in degrees.
+#
+# Key features:
+# - Converts OKLAB rectangular coordinates to OKLCH cylindrical coordinates
+# - Preserves lightness component unchanged during conversion
+# - Calculates chroma as sqrt(a² + b²) for colorfulness representation
+# - Computes hue angle using atan2 function and normalizes to 0-360 degree range
+# - Maintains alpha channel transparency values during conversion
+# - Uses AbcDecimal arithmetic for precise color science calculations
+# - Validates input color space to ensure proper OKLAB source data
+#
+# The OKLCH color space provides an intuitive interface for color manipulation through
+# its cylindrical coordinate system, making it ideal for hue adjustments, saturation
+# modifications, and other color operations that benefit from polar coordinates.
 
 module Abachrome
   module Converters
     class OklabToOklch < Abachrome::Converters::Base
+      # Converts a color from OKLAB color space to OKLCH color space.
+      # The method performs a mathematical transformation from the rectangular
+      # coordinates (L, a, b) to cylindrical coordinates (L, C, h), where:
+      # - L (lightness) remains the same
+      # - C (chroma) is calculated as the Euclidean distance from the origin in the a-b plane
+      # - h (hue) is calculated as the angle in the a-b plane
+      # 
+      # @param oklab_color [Abachrome::Color] A color in the OKLAB color space
+      # @raise [ArgumentError] If the provided color is not in OKLAB color space
+      # @return [Abachrome::Color] The equivalent color in OKLCH color space with the same alpha value
       def self.convert(oklab_color)
         raise_unless oklab_color, :oklab
 
@@ -20,4 +49,4 @@ module Abachrome
       end
     end
   end
-end
+end

data/lib/abachrome/converters/oklab_to_srgb.rb

@@ -1,8 +1,33 @@
-# frozen_string_literal: true
+# Abachrome::Converters::OklabToSrgb - OKLAB to sRGB color space converter
+#
+# This converter transforms colors from the OKLAB color space to the standard RGB (sRGB) color space
+# through a two-step conversion process. The transformation first converts OKLAB coordinates to
+# linear RGB as an intermediate step, then applies gamma correction to produce the final sRGB
+# values suitable for display on standard monitors and web applications.
+#
+# Key features:
+# - Two-stage conversion pipeline: OKLAB → Linear RGB → sRGB
+# - Leverages existing OklabToLrgb and LrgbToSrgb converters for modular transformation
+# - Maintains alpha channel transparency values during conversion
+# - Applies proper gamma correction for display-ready color values
+# - Uses AbcDecimal arithmetic for precise color science calculations
+# - Validates input color space to ensure proper OKLAB source data
+#
+# The sRGB color space is the standard RGB color space for web content and most consumer
+# displays, providing gamma-corrected values that properly represent colors on typical
+# display devices while maintaining compatibility with web standards and digital media formats.
 
 module Abachrome
   module Converters
     class OklabToSrgb < Abachrome::Converters::Base
+      # Converts a color from the Oklab color space to the sRGB color space.
+      # This conversion is performed in two steps:
+      # 1. First converts from Oklab to linear RGB
+      # 2. Then converts from linear RGB to sRGB
+      # 
+      # @param oklab_color [Color] A color in the Oklab color space
+      # @raise [ArgumentError] If the provided color is not in the Oklab color space
+      # @return [Color] The converted color in the sRGB color space
       def self.convert(oklab_color)
         raise_unless oklab_color, :oklab
 
@@ -14,4 +39,4 @@ module Abachrome
       end
     end
   end
-end
+end