abachrome-float 0.1.6

data/lib/abachrome/color_mixins/lighten.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+# Abachrome::ColorMixins::Lighten - Color lightness adjustment functionality
+#
+# This mixin provides methods for adjusting the lightness of colors by manipulating
+# the L (lightness) component in the OKLAB color space. The OKLAB color space is used
+# because it provides perceptually uniform lightness adjustments that appear more
+# natural to the human eye compared to adjustments in other color spaces.
+#
+# Key features:
+# - Lighten and darken colors with configurable amounts
+# - Both non-destructive (lighten/darken) and destructive (lighten!/darken!) variants
+# - Automatic clamping to valid lightness ranges [0, 1]
+# - High-precision decimal arithmetic for accurate color calculations
+# - Conversion to OKLAB color space for perceptually uniform adjustments
+#
+# The mixin includes both immutable methods that return new color instances and mutable
+# methods that modify the current color object in place, providing flexibility for
+# different use cases and performance requirements.
+
+module Abachrome
+  module ColorMixins
+    module Lighten
+      # Increases the lightness of a color by the specified amount in the OKLab color space.
+      # This method works by extracting the L (lightness) component from the OKLab
+      # representation of the color and increasing it by the given amount, ensuring
+      # the result stays within the valid range of [0, 1].
+      #
+      # @param amount [Numeric] The amount to increase the lightness by, as a decimal
+      # value between 0 and 1. Defaults to 0.1 (10% increase).
+      # @return [Abachrome::Color] A new Color instance with increased lightness.
+      def lighten(amount = 0.1)
+        amount = amount.to_f
+        oklab = to_oklab
+        l, a, b = oklab.coordinates
+
+        new_l = l + amount
+        new_l = "1.0".to_f if new_l > 1
+        new_l = "0.0".to_f if new_l.negative?
+
+        Color.new(
+          ColorSpace.find(:oklab),
+          [new_l, a, b],
+          alpha
+        )
+      end
+
+      # Increases the lightness of the color by the specified amount and modifies the current color object.
+      # This method changes the color in-place, mutating the current object. The color
+      # is converted to a lightness-based color space if needed to perform the operation.
+      #
+      # @param amount [Float] The amount to increase the lightness by, as a decimal value
+      # between 0 and 1. Default is 0.1 (10% increase).
+      # @return [Abachrome::Color] Returns self for method chaining.
+      def lighten!(amount = 0.1)
+        lightened = lighten(amount)
+        @color_space = lightened.color_space
+        @coordinates = lightened.coordinates
+        @alpha = lightened.alpha
+        self
+      end
+
+      # Darkens a color by decreasing its lightness value.
+      #
+      # This method is effectively a convenience wrapper around the {#lighten} method,
+      # passing a negative amount value to decrease the lightness instead of increasing it.
+      #
+      # @param amount [Float] The amount to darken the color by, between 0 and 1.
+      # Defaults to 0.1 (10% darker).
+      # @return [Color] A new color instance with decreased lightness.
+      # @see #lighten
+      def darken(amount = 0.1)
+        lighten(-amount)
+      end
+
+      # Decreases the lightness value of the color by the specified amount.
+      # Modifies the color in place.
+      #
+      # @param amount [Float] The amount to darken the color by, as a value between 0 and 1.
+      # Defaults to 0.1 (10% darker).
+      # @return [Abachrome::Color] Returns self with the modified lightness value.
+      # @see #lighten!
+      def darken!(amount = 0.1)
+        lighten!(-amount)
+      end
+    end
+  end
+end
+
+# Copyright (c) 2025 Durable Programming, LLC. All rights reserved.

data/lib/abachrome/color_mixins/spectral_mix.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+# Abachrome::ColorMixins::SpectralMix - Kubelka-Munk spectral color mixing
+#
+# This mixin adds spectral mixing capabilities to Color objects using the
+# Kubelka-Munk theory for realistic paint-like color mixing.
+#
+# Unlike simple RGB blending or interpolation in perceptual color spaces,
+# spectral mixing simulates how real pigments interact with light through
+# absorption and scattering. This produces more realistic results, especially
+# when mixing complementary colors.
+#
+# Key features:
+# - Physics-based color mixing using Kubelka-Munk theory
+# - Avoids muddy browns when mixing complementary colors
+# - Supports tinting strength for different pigment concentrations
+# - More realistic than linear RGB or LAB interpolation
+
+module Abachrome
+  module ColorMixins
+    module SpectralMix
+      # Mix this color with another color using Kubelka-Munk spectral mixing.
+      #
+      # This method produces more realistic color mixing than simple RGB or LAB
+      # interpolation by simulating how real pigments absorb and scatter light.
+      #
+      # @param other [Abachrome::Color] The color to mix with
+      # @param amount [Float] The mix ratio, between 0 and 1. 0.5 means equal mixing.
+      #   Values closer to 0 favor this color, values closer to 1 favor the other color.
+      # @param tinting_strength_self [Float] Tinting strength of this color (default: 1.0)
+      #   Higher values mean stronger pigment concentration
+      # @param tinting_strength_other [Float] Tinting strength of other color (default: 1.0)
+      # @return [Abachrome::Color] A new color representing the spectral mix
+      #
+      # @example Mix red and blue equally
+      #   red = Abachrome.from_rgb(1, 0, 0)
+      #   blue = Abachrome.from_rgb(0, 0, 1)
+      #   purple = red.spectral_mix(blue, 0.5)
+      #
+      # @example Mix with 25% of blue
+      #   mostly_red = red.spectral_mix(blue, 0.25)
+      #
+      # @example Mix with different tinting strengths
+      #   # Stronger blue pigment
+      #   purple = red.spectral_mix(blue, 0.5, tinting_strength_other: 2.0)
+      def spectral_mix(other, amount = 0.5, tinting_strength_self: 1.0, tinting_strength_other: 1.0)
+        require_relative "../spectral"
+
+        # Convert amount to weights
+        # amount = 0 means 100% self, 0% other
+        # amount = 0.5 means 50% self, 50% other
+        # amount = 1 means 0% self, 100% other
+        weight_self = 1.0 - amount.to_f
+        weight_other = amount.to_f
+
+        colors = [
+          { color: self, weight: weight_self },
+          { color: other, weight: weight_other }
+        ]
+
+        tinting_strengths = {
+          self => tinting_strength_self.to_f,
+          other => tinting_strength_other.to_f
+        }
+
+        Spectral.mix(colors, tinting_strengths: tinting_strengths)
+      end
+    end
+  end
+end

data/lib/abachrome/color_mixins/to_colorspace.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+# Abachrome::ColorMixins::ToColorspace - Color space conversion functionality
+#
+# This mixin provides methods for converting colors between different color spaces within
+# the Abachrome library. It includes both immutable and mutable conversion methods that
+# allow colors to be transformed from their current color space to any registered target
+# color space, such as sRGB, OKLAB, OKLCH, or linear RGB.
+#
+# Key features:
+# - Convert colors to any registered color space with automatic converter lookup
+# - Both non-destructive (to_color_space/convert_to/in_color_space) and destructive variants
+# - Optimized to return the same object when no conversion is needed
+# - Flexible API with multiple method names for different use cases and preferences
+# - Integration with the Converter system for extensible color space transformations
+#
+# The mixin provides a consistent interface for color space conversions while maintaining
+# the precision and accuracy required for color science calculations through the use of
+# the underlying converter infrastructure.
+
+module Abachrome
+  module ColorMixins
+    module ToColorspace
+      # Converts the current color to the specified target color space.
+      #
+      # This method transforms the current color into an equivalent color in a different
+      # color space. If the target space is the same as the current color space, no
+      # conversion is performed and the current color is returned.
+      #
+      # @param target_space [Abachrome::ColorSpace] The target color space to convert to
+      # @return [Abachrome::Color] A new color object in the target color space, or self
+      # if the target space is the same as the current color space
+      def to_color_space(target_space)
+        return self if color_space == target_space
+
+        Converter.convert(self, target_space.name)
+      end
+
+      # Converts the color object to the specified target color space in-place.
+      # This method modifies the current object by changing its color space and
+      # coordinates to match the target color space.
+      #
+      # @param target_space [Abachrome::ColorSpace] The color space to convert to
+      # @return [Abachrome::Color] Returns self with modified color space and coordinates
+      # @see #to_color_space The non-destructive version that returns a new color object
+      def to_color_space!(target_space)
+        unless color_space == target_space
+          converted = to_color_space(target_space)
+          @color_space = converted.color_space
+          @coordinates = converted.coordinates
+        end
+        self
+      end
+
+      # Convert this color to a different color space.
+      #
+      # @param space_name [String, Symbol] The name of the target color space to convert to.
+      # @return [Abachrome::Color] A new Color object in the specified color space.
+      # @example
+      # # Convert a color from sRGB to OKLCH
+      # rgb_color.convert_to(:oklch)
+      # @see Abachrome::ColorSpace.find
+      # @see #to_color_space
+      def convert_to(space_name)
+        to_color_space(ColorSpace.find(space_name))
+      end
+
+      # Converts this color to the specified color space in place.
+      #
+      # @param space_name [String, Symbol] The name or identifier of the target color space to convert to.
+      # @return [Abachrome::Color] Returns self with its values converted to the specified color space.
+      # @raise [Abachrome::ColorSpaceNotFoundError] If the specified color space is not registered.
+      # @see Abachrome::ColorSpace.find
+      # @example
+      # red = Abachrome::Color.new(1, 0, 0, color_space: :srgb)
+      # red.convert_to!(:oklch) # Converts the red color to OKLCH space in place
+      def convert_to!(space_name)
+        to_color_space!(ColorSpace.find(space_name))
+      end
+
+      # Convert a color to a specified color space.
+      #
+      # @param space_name [Symbol, String] The name of the color space to convert to.
+      # @return [Abachrome::Color] A new Color instance in the specified color space.
+      # @example
+      # red_rgb = Abachrome::Color.new(:srgb, [1, 0, 0])
+      # red_lch = red_rgb.in_color_space(:oklch)
+      def in_color_space(space_name)
+        convert_to(space_name)
+      end
+
+      # Converts the color to the specified color space and mutates the current object.
+      #
+      # @param space_name [Symbol, String] The target color space to convert to (e.g., :oklch, :rgb, :lab)
+      # @return [Abachrome::Color] Returns self after conversion
+      # @see #convert_to!
+      # @example
+      # color = Abachrome::Color.new([255, 0, 0], :rgb)
+      # color.in_color_space!(:oklch) # Color is now in OKLCH space
+      def in_color_space!(space_name)
+        convert_to!(space_name)
+      end
+    end
+  end
+end
+
+# Copyright (c) 2025 Durable Programming, LLC. All rights reserved.

data/lib/abachrome/color_mixins/to_grayscale.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+# Abachrome::ColorMixins::ToGrayscale - Grayscale conversion mixin
+#
+# This mixin provides methods for converting colors to grayscale using various
+# standard luma calculations. It supports both legacy Rec. 601 (SDTV) and modern
+# Rec. 709 (HDTV) coefficients for accurate grayscale conversion based on human
+# eye sensitivity.
+#
+# Key features:
+# - Rec. 601 luma: Y = 0.299R + 0.587G + 0.114B (NTSC/SDTV standard)
+# - Rec. 709 luma: Y = 0.2126R + 0.7152G + 0.0722B (HDTV standard)
+# - Maintains alpha channel during conversion
+# - Uses BigDecimal for precise calculations
+#
+# This is essential for image processing, accessibility checks, and any application
+# that needs perceptually accurate grayscale conversion rather than simple averaging.
+
+module Abachrome
+  module ColorMixins
+    module ToGrayscale
+      # Converts the color to grayscale using Rec. 601 luma coefficients (legacy NTSC standard).
+      # This is the same calculation used in the YIQ color space's Y component.
+      #
+      # @return [Abachrome::Color] A grayscale version of the color in sRGB space
+      def to_grayscale_601
+        rgb_color = to_srgb
+        r, g, b = rgb_color.coordinates
+
+        # Rec. 601 luma: Y = 0.299R + 0.587G + 0.114B
+        luma = (AD("0.299") * r) + (AD("0.587") * g) + (AD("0.114") * b)
+
+        Color.from_rgb(luma, luma, luma, alpha)
+      end
+
+      # Converts the color to grayscale using Rec. 709 luma coefficients (HDTV standard).
+      #
+      # @return [Abachrome::Color] A grayscale version of the color in sRGB space
+      def to_grayscale_709
+        rgb_color = to_srgb
+        r, g, b = rgb_color.coordinates
+
+        # Rec. 709 luma: Y = 0.2126R + 0.7152G + 0.0722B
+        luma = (AD("0.2126") * r) + (AD("0.7152") * g) + (AD("0.0722") * b)
+
+        Color.from_rgb(luma, luma, luma, alpha)
+      end
+
+      # Converts the color to grayscale using the default Rec. 601 standard.
+      # This is an alias for to_grayscale_601 and matches the legacy behavior
+      # expected by most image processing applications.
+      #
+      # @return [Abachrome::Color] A grayscale version of the color in sRGB space
+      def to_grayscale
+        to_grayscale_601
+      end
+
+      # Calculates the relative luminance (luma) value using Rec. 601 coefficients.
+      # This returns just the Y component without creating a new color.
+      #
+      # @return [AbcDecimal] The luma value in range [0, 1]
+      def luma_601
+        rgb_color = to_srgb
+        r, g, b = rgb_color.coordinates
+        (AD("0.299") * r) + (AD("0.587") * g) + (AD("0.114") * b)
+      end
+
+      # Calculates the relative luminance (luma) value using Rec. 709 coefficients.
+      # This returns just the Y component without creating a new color.
+      #
+      # @return [AbcDecimal] The luma value in range [0, 1]
+      def luma_709
+        rgb_color = to_srgb
+        r, g, b = rgb_color.coordinates
+        (AD("0.2126") * r) + (AD("0.7152") * g) + (AD("0.0722") * b)
+      end
+
+      # Calculates the relative luminance using the default Rec. 601 standard.
+      # Alias for luma_601.
+      #
+      # @return [AbcDecimal] The luma value in range [0, 1]
+      def luma
+        luma_601
+      end
+    end
+  end
+end

data/lib/abachrome/color_mixins/to_lrgb.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+# Abachrome::ColorMixins::ToLrgb - Linear RGB color space conversion functionality
+#
+# This mixin provides methods for converting colors to the linear RGB (LRGB) color space,
+# which uses a linear relationship between stored numeric values and actual light intensity.
+# Linear RGB is essential for accurate color calculations and serves as an intermediate
+# color space for many color transformations, particularly when converting between
+# different color models.
+#
+# Key features:
+# - Convert colors to linear RGB with automatic converter lookup
+# - Both non-destructive (to_lrgb) and destructive (to_lrgb!) conversion methods
+# - Direct access to linear RGB components (lred, lgreen, lblue)
+# - Utility methods for RGB array and hex string output
+# - Optimized to return the same object when no conversion is needed
+# - High-precision decimal arithmetic for accurate color science calculations
+#
+# The linear RGB color space differs from standard sRGB by removing gamma correction,
+# making it suitable for mathematical operations like blending, lighting calculations,
+# and color space transformations that require linear light behavior.
+
+require_relative "../converter"
+
+module Abachrome
+  module ColorMixins
+    module ToLrgb
+      # Converts this color to the Linear RGB (LRGB) color space.
+      # This method transforms the current color to the linear RGB color space,
+      # which uses a linear relationship between the stored numeric value and
+      # the actual light intensity. If the color is already in the LRGB space,
+      # it returns the current object without conversion.
+      #
+      # @return [Abachrome::Color] A new color object in the LRGB color space,
+      # or the original object if already in LRGB space
+      def to_lrgb
+        return self if color_space.name == :lrgb
+
+        Converter.convert(self, :lrgb)
+      end
+
+      # Converts the current color to the linear RGB (LRGB) color space and updates
+      # the receiver's state. If the color is already in LRGB space, this is a no-op.
+      #
+      # Unlike #to_lrgb which returns a new color instance, this method modifies the
+      # current object by changing its color space and coordinates to the LRGB equivalent.
+      #
+      # @return [Abachrome::Color] the receiver itself, now in LRGB color space
+      def to_lrgb!
+        unless color_space.name == :lrgb
+          lrgb_color = to_lrgb
+          @color_space = lrgb_color.color_space
+          @coordinates = lrgb_color.coordinates
+        end
+        self
+      end
+
+      # Returns the linear red component value of the color.
+      #
+      # This method accesses the first coordinate from the color in linear RGB space.
+      # Linear RGB values differ from standard RGB by using a non-gamma-corrected
+      # linear representation of luminance.
+      #
+      # @return [AbcDecimal] The linear red component value, typically in range [0, 1]
+      def lred
+        to_lrgb.coordinates[0]
+      end
+
+      # Retrieves the linear green (lgreen) coordinate from a color by converting it to
+      # linear RGB color space first. Linear RGB uses a different scale than standard
+      # sRGB, with values representing linear light energy rather than gamma-corrected
+      # values.
+      #
+      # @return [AbcDecimal] The linear green component value from the color's linear
+      # RGB representation
+      def lgreen
+        to_lrgb.coordinates[1]
+      end
+
+      # Returns the linear blue channel value of this color after conversion to linear RGB color space.
+      #
+      # This method converts the current color to the linear RGB color space and extracts the blue
+      # component (the third coordinate).
+      #
+      # @return [AbcDecimal] The linear blue component value, typically in the range [0, 1]
+      def lblue
+        to_lrgb.coordinates[2]
+      end
+
+      # Returns the coordinates of the color in the linear RGB color space.
+      #
+      # @return [Array<AbcDecimal>] An array of three AbcDecimal values representing
+      # the red, green, and blue components in linear RGB color space.
+      def lrgb_values
+        to_lrgb.coordinates
+      end
+
+      # Returns an array of sRGB values as integers in the 0-255 range.
+      # This method converts the color to RGB, scales the values to the 0-255 range,
+      # rounds to integers, and ensures they are clamped within the valid range.
+      #
+      # @return [Array<Integer>] An array of three RGB integer values between 0-255
+      def rgb_array
+        to_rgb.coordinates.map { |c| (c * 255).round.clamp(0, 255) }
+      end
+
+      # Returns a hexadecimal string representation of the color in RGB format.
+      #
+      # @return [String] A hexadecimal color code in the format '#RRGGBB' where RR, GG, and BB
+      # are two-digit hexadecimal values for the red, green, and blue components respectively.
+      # @example
+      # color.rgb_hex  # => "#1a2b3c"
+      def rgb_hex
+        r, g, b = rgb_array
+        format("#%02x%02x%02x", r, g, b)
+      end
+    end
+  end
+end
+
+# Copyright (c) 2025 Durable Programming, LLC. All rights reserved.

data/lib/abachrome/color_mixins/to_oklab.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+# Abachrome::ColorMixins::ToOklab - OKLAB color space conversion functionality
+#
+# This mixin provides methods for converting colors to the OKLAB color space, which is a
+# perceptually uniform color space designed for better color manipulation and comparison.
+# OKLAB provides more intuitive lightness adjustments and color blending compared to
+# traditional RGB color spaces, making it ideal for color science applications.
+#
+# Key features:
+# - Convert colors to OKLAB with automatic converter lookup
+# - Both non-destructive (to_oklab) and destructive (to_oklab!) conversion methods
+# - Direct access to OKLAB components (lightness, a, b)
+# - Utility methods for OKLAB array and value extraction
+# - Optimized to return the same object when no conversion is needed
+# - High-precision decimal arithmetic for accurate color science calculations
+#
+# The OKLAB color space uses three components: L (lightness), a (green-red axis), and
+# b (blue-yellow axis), providing a more perceptually uniform representation of colors
+# that better matches human visual perception compared to traditional color spaces.
+
+require_relative "../converter"
+
+module Abachrome
+  module ColorMixins
+    module ToOklab
+      # Converts the current color to the OKLAB color space.
+      #
+      # If the color is already in OKLAB, it returns the color unchanged.
+      # Otherwise, it uses the Converter to transform the color to OKLAB.
+      #
+      # @return [Abachrome::Color] A new Color object in the OKLAB color space
+      def to_oklab
+        return self if color_space.name == :oklab
+
+        Converter.convert(self, :oklab)
+      end
+
+      # Converts the color to the OKLAB color space in place.
+      # This method transforms the current color into OKLAB space,
+      # modifying the original object by updating its color space
+      # and coordinates if not already in OKLAB.
+      #
+      # @example
+      # color = Abachrome::Color.from_hex("#ff5500")
+      # color.to_oklab!  # Color now uses OKLAB color space
+      #
+      # @return [Abachrome::Color] self, with updated color space and coordinates
+      def to_oklab!
+        unless color_space.name == :oklab
+          oklab_color = to_oklab
+          @color_space = oklab_color.color_space
+          @coordinates = oklab_color.coordinates
+        end
+        self
+      end
+
+      # Returns the lightness component (L) of the color in the OKLAB color space.
+      # The lightness value ranges from 0 (black) to 1 (white) and represents
+      # the perceived lightness of the color.
+      #
+      # @return [AbcDecimal] The lightness (L) value from the OKLAB color space
+      def lightness
+        to_oklab.coordinates[0]
+      end
+
+      # Returns the L (Lightness) component from the OKLAB color space.
+      #
+      # The L value represents perceptual lightness in the OKLAB color space,
+      # typically ranging from 0 (black) to 1 (white).
+      #
+      # @return [AbcDecimal] The L (Lightness) component from the OKLAB color space
+      def l
+        to_oklab.coordinates[0]
+      end
+
+      # Returns the 'a' component from the OKLAB color space (green-red axis).
+      #
+      # The 'a' component in OKLAB represents the position on the green-red axis,
+      # with negative values being more green and positive values being more red.
+      #
+      # @return [AbcDecimal] The 'a' component value from the OKLAB color space.
+      # @see #to_oklab For the full conversion to OKLAB color space
+      def a
+        to_oklab.coordinates[1]
+      end
+
+      # Returns the B value of the color in OKLAB color space.
+      #
+      # This method first converts the color to OKLAB color space if needed,
+      # then extracts the B component (blue-yellow axis), which is the third
+      # coordinate in the OKLAB model.
+      #
+      # @return [AbcDecimal] The B component value in OKLAB color space
+      def b
+        to_oklab.coordinates[2]
+      end
+
+      # Returns the OKLAB color space coordinates for this color.
+      #
+      # @return [Array] An array of OKLAB coordinates [L, a, b] representing the color in OKLAB color space
+      def oklab_values
+        to_oklab.coordinates
+      end
+
+      # Returns an array representation of the color's coordinates in the OKLAB color space.
+      #
+      # @return [Array<AbcDecimal>] An array containing the coordinates of the color
+      # in the OKLAB color space in the order [L, a, b]
+      def oklab_array
+        to_oklab.coordinates
+      end
+    end
+  end
+end
+
+# Copyright (c) 2025 Durable Programming, LLC. All rights reserved.