abachrome-float 0.1.6

data/lib/abachrome/converters/srgb_to_cmyk.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+# Abachrome::Converters::SrgbToCmyk - sRGB to CMYK color space converter
+#
+# This converter transforms colors from the standard RGB (sRGB) color space to the CMYK
+# (Cyan, Magenta, Yellow, Key/Black) color space using Gray Component Replacement (GCR)
+# for optimal ink usage in print production.
+#
+# Key features:
+# - Implements GCR/UCR for efficient ink usage and better print quality
+# - Converts from additive (light) to subtractive (ink) color model
+# - Configurable GCR amount for different printing requirements
+# - Uses BigDecimal for precise ink percentage calculations
+# - Maintains alpha channel transparency values during conversion
+# - Produces professional-quality CMYK separations
+#
+# The conversion uses Gray Component Replacement by default, which extracts the neutral
+# gray component from CMY inks and assigns it to the cheaper and more stable Black (K) ink.
+# This reduces Total Area Coverage (TAC) and improves print quality.
+
+module Abachrome
+  module Converters
+    class SrgbToCmyk
+      # Converts a color from sRGB color space to CMYK color space.
+      # Uses full GCR (Gray Component Replacement) by default for optimal ink usage.
+      #
+      # @param srgb_color [Abachrome::Color] A color object in the sRGB color space
+      # @param gcr_amount [Numeric] The amount of GCR to apply (0.0 to 1.0), default 1.0 for full GCR
+      # @return [Abachrome::Color] A new color object in the CMYK color space
+      # with the same alpha value as the input color
+      def self.convert(srgb_color, gcr_amount: 1.0)
+        r, g, b = srgb_color.coordinates.map { |c| c.to_f }
+
+        # Use GCR conversion from the CMYK color model
+        c, m, y, k = ColorModels::CMYK.from_rgb_gcr(r, g, b, gcr_amount)
+
+        Color.new(
+          ColorSpace.find(:cmyk),
+          [c, m, y, k],
+          srgb_color.alpha
+        )
+      end
+
+      # Converts a color from sRGB to CMYK using the naive method (no UCR/GCR).
+      # This produces higher ink coverage but simpler conversion.
+      # Generally not recommended for production printing.
+      #
+      # @param srgb_color [Abachrome::Color] A color object in the sRGB color space
+      # @return [Abachrome::Color] A new color object in the CMYK color space
+      def self.convert_naive(srgb_color)
+        r, g, b = srgb_color.coordinates.map { |c| c.to_f }
+
+        # Use naive conversion from the CMYK color model
+        c, m, y, k = ColorModels::CMYK.from_rgb_naive(r, g, b)
+
+        Color.new(
+          ColorSpace.find(:cmyk),
+          [c, m, y, k],
+          srgb_color.alpha
+        )
+      end
+    end
+  end
+end

data/lib/abachrome/converters/srgb_to_lrgb.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+# Abachrome::Converters::SrgbToLrgb - sRGB to Linear RGB color space converter
+#
+# This converter transforms colors from the standard RGB (sRGB) color space to the linear RGB (LRGB) color space by removing gamma correction. The conversion process applies the inverse sRGB transfer function which uses different formulas for small and large values to convert from the gamma-corrected sRGB representation to linear light intensity values.
+#
+# Key features:
+# - Implements the standard sRGB to linear RGB conversion algorithm with precise threshold handling
+# - Converts gamma-corrected sRGB values to linear RGB values for accurate color calculations
+# - 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 sRGB 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.
+
+module Abachrome
+  module Converters
+    class SrgbToLrgb
+      # Converts a color from sRGB color space to linear RGB color space.
+      # This method performs gamma correction by linearizing each sRGB coordinate.
+      #
+      # @param srgb_color [Abachrome::Color] A color object in the sRGB color space
+      # @return [Abachrome::Color] A new color object in the linear RGB (LRGB) color space
+      # with the same alpha value as the input color
+      def self.convert(srgb_color)
+        r, g, b = srgb_color.coordinates.map { |c| to_linear(c.to_f) }
+
+        Color.new(
+          ColorSpace.find(:lrgb),
+          [r, g, b],
+          srgb_color.alpha
+        )
+      end
+
+      # Converts a sRGB component to its linear RGB equivalent.
+      # This conversion applies the appropriate gamma correction to transform an sRGB value
+      # into a linear RGB value.
+      #
+      # @param v [AbcDecimal, Numeric] The sRGB component value to convert (typically in range 0-1)
+      # @return [AbcDecimal] The corresponding linear RGB component value
+      def self.to_linear(v)
+        v_abs = v.abs
+        v_sign = v.negative? ? -1 : 1
+        if v_abs <= AD("0.04045")
+          v / AD("12.92")
+        else
+          v_sign * (((v_abs + AD("0.055")) / AD("1.055"))**AD("2.4"))
+        end
+      end
+    end
+  end
+end
+
+# Copyright (c) 2025 Durable Programming, LLC. All rights reserved.

data/lib/abachrome/converters/srgb_to_oklab.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+# Abachrome::Converters::SrgbToOklab - sRGB to OKLAB color space converter
+#
+# This converter transforms colors from the standard RGB (sRGB) color space to the OKLAB color space
+# through a two-step conversion process. The transformation first converts sRGB gamma-corrected
+# values to linear RGB as an intermediate step, then applies the standard OKLAB transformation
+# matrices to produce the final perceptually uniform OKLAB coordinates.
+#
+# Key features:
+# - Two-stage conversion pipeline: sRGB → Linear RGB → OKLAB
+# - Leverages existing SrgbToLrgb and LrgbToOklab converters for modular transformation
+# - Removes gamma correction and applies perceptual uniformity transformations
+# - Maintains alpha channel transparency values during conversion
+# - Uses AbcDecimal arithmetic for precise color science calculations
+# - Validates input color space to ensure proper sRGB 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. This converter enables
+# seamless transformation from display-ready sRGB values to the scientifically accurate OKLAB
+# representation for advanced color processing workflows.
+
+module Abachrome
+  module Converters
+    class SrgbToOklab
+      # Converts a color from sRGB color space to Oklab color space.
+      # The conversion happens in two steps:
+      # 1. sRGB is first converted to linear RGB
+      # 2. Linear RGB is then converted to Oklab
+      #
+      # @param srgb_color [Abachrome::Color] The color in sRGB color space to convert
+      # @return [Abachrome::Color] The converted color in Oklab color space
+      def self.convert(srgb_color)
+        # First convert sRGB to linear RGB
+        lrgb_color = SrgbToLrgb.convert(srgb_color)
+
+        # Then convert linear RGB to Oklab
+        LrgbToOklab.convert(lrgb_color)
+      end
+    end
+  end
+end
+
+# Copyright (c) 2025 Durable Programming, LLC. All rights reserved.

data/lib/abachrome/converters/srgb_to_oklch.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+# Abachrome::Converters::SrgbToOklch - sRGB to OKLCH color space converter
+#
+# This converter transforms colors from the standard RGB (sRGB) color space to the OKLCH color space
+# through a two-step conversion process. The transformation first converts sRGB gamma-corrected
+# values to OKLAB rectangular coordinates as an intermediate step, then applies cylindrical coordinate
+# conversion to produce the final OKLCH values with lightness, chroma, and hue components.
+#
+# Key features:
+# - Two-stage conversion pipeline: sRGB → OKLAB → OKLCH
+# - Leverages existing SrgbToOklab and OklabToOklch converters for modular transformation
+# - Converts display-ready RGB values to perceptually uniform cylindrical coordinates
+# - Maintains alpha channel transparency values during conversion
+# - Uses AbcDecimal arithmetic for precise color science calculations
+# - Validates input color space to ensure proper sRGB 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 while maintaining perceptual
+# uniformity for natural-looking color transformations.
+
+require_relative "srgb_to_oklab"
+require_relative "oklab_to_oklch"
+
+module Abachrome
+  module Converters
+    class SrgbToOklch < Abachrome::Converters::Base
+      # Converts an sRGB color to OKLCH color space
+      #
+      # @param srgb_color [Abachrome::Color] The color in sRGB color space to convert
+      # @return [Abachrome::Color] The converted color in OKLCH color space
+      # @note This is a two-step conversion process: first from sRGB to OKLab, then from OKLab to OKLCH
+      # @see SrgbToOklab
+      # @see OklabToOklch
+      def self.convert(srgb_color)
+        # First convert sRGB to OKLab
+        oklab_color = SrgbToOklab.convert(srgb_color)
+
+        # Then convert OKLab to OKLCh
+        OklabToOklch.convert(oklab_color)
+      end
+    end
+  end
+end
+
+# Copyright (c) 2025 Durable Programming, LLC. All rights reserved.

data/lib/abachrome/converters/srgb_to_yiq.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+# Abachrome::Converters::SrgbToYiq - sRGB to YIQ color space converter
+#
+# This converter transforms colors from the standard RGB (sRGB) color space to the YIQ
+# color space using the NTSC standard transformation matrix. The conversion applies the
+# Rec. 601 luma coefficients to separate luminance (Y) from chrominance (I and Q).
+#
+# Key features:
+# - Implements the standard NTSC RGB to YIQ conversion using matrix transformation
+# - Separates brightness (Y) from color information (I, Q)
+# - Uses Rec. 601 luma coefficients: Y = 0.299R + 0.587G + 0.114B
+# - I axis represents orange-to-blue chrominance
+# - Q axis represents purple-to-green chrominance
+# - Maintains alpha channel transparency values during conversion
+# - Uses AbcDecimal arithmetic for precise color science calculations
+#
+# The YIQ color space is historically significant for broadcast television and remains
+# relevant for image processing tasks that require luminance/chrominance separation.
+
+module Abachrome
+  module Converters
+    class SrgbToYiq
+      # Converts a color from sRGB color space to YIQ color space.
+      # This method applies the NTSC standard transformation matrix.
+      #
+      # @param srgb_color [Abachrome::Color] A color object in the sRGB color space
+      # @return [Abachrome::Color] A new color object in the YIQ color space
+      # with the same alpha value as the input color
+      def self.convert(srgb_color)
+        r, g, b = srgb_color.coordinates.map { |c| c.to_f }
+
+        # NTSC RGB to YIQ transformation matrix
+        # Y = 0.299R + 0.587G + 0.114B  (Rec. 601 luma)
+        # I = 0.596R - 0.275G - 0.321B  (In-phase: orange-blue)
+        # Q = 0.212R - 0.523G + 0.311B  (Quadrature: purple-green)
+        y = (AD("0.299") * r) + (AD("0.587") * g) + (AD("0.114") * b)
+        i = (AD("0.5959") * r) - (AD("0.2746") * g) - (AD("0.3213") * b)
+        q = (AD("0.2115") * r) - (AD("0.5227") * g) + (AD("0.3112") * b)
+
+        Color.new(
+          ColorSpace.find(:yiq),
+          [y, i, q],
+          srgb_color.alpha
+        )
+      end
+    end
+  end
+end

data/lib/abachrome/converters/xyz_to_lms.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Abachrome
+  module Converters
+    class XyzToLms < Abachrome::Converters::Base
+      # Converts a color from XYZ color space to LMS color space.
+      #
+      # This method implements the XYZ to LMS 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 xyz_color [Abachrome::Color] The color in XYZ color space
+      # @raise [ArgumentError] If the input color is not in XYZ color space
+      # @return [Abachrome::Color] The resulting color in LMS color space with
+      # the same alpha as the input color
+      def self.convert(xyz_color)
+        raise_unless xyz_color, :xyz
+
+        x, y, z = xyz_color.coordinates.map { |_| _.to_f }
+
+        # XYZ to LMS transformation matrix
+        l = (x * AD("0.8189330101")) + (y * AD("0.3618667424")) - (z * AD("0.1288597137"))
+        m = (x * AD("0.0329845436")) + (y * AD("0.9293118715")) + (z * AD("0.0361456387"))
+        s = (x * AD("0.0482003018")) + (y * AD("0.2643662691")) + (z * AD("0.6338517070"))
+
+        Color.new(ColorSpace.find(:lms), [l, m, s], xyz_color.alpha)
+      end
+    end
+  end
+end
+
+# Copyright (c) 2025 Durable Programming, LLC. All rights reserved.

data/lib/abachrome/converters/xyz_to_oklab.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Abachrome
+  module Converters
+    class XyzToOklab < Abachrome::Converters::Base
+      # Converts a color from XYZ color space to OKLAB color space.
+      #
+      # This method implements the XYZ to OKLAB transformation by first
+      # converting XYZ coordinates to the intermediate LMS (Long, Medium, Short)
+      # color space, then applying the LMS to OKLAB transformation matrix.
+      #
+      # @param xyz_color [Abachrome::Color] The color in XYZ color space
+      # @raise [ArgumentError] If the input color is not in XYZ color space
+      # @return [Abachrome::Color] The resulting color in OKLAB color space with
+      # the same alpha as the input color
+      def self.convert(xyz_color)
+        raise_unless xyz_color, :xyz
+
+        x, y, z = xyz_color.coordinates.map { |_| _.to_f }
+
+        # XYZ to LMS transformation matrix
+        l = (x * AD("0.8189330101")) + (y * AD("0.3618667424")) - (z * AD("0.1288597137"))
+        m = (x * AD("0.0329845436")) + (y * AD("0.9293118715")) + (z * AD("0.0361456387"))
+        s = (x * AD("0.0482003018")) + (y * AD("0.2643662691")) + (z * AD("0.6338517070"))
+
+        # Apply cube root transformation
+        l_ = l.to_f**Rational(1, 3)
+        m_ = m.to_f**Rational(1, 3)
+        s_ = s.to_f**Rational(1, 3)
+
+        # LMS to OKLAB transformation matrix
+        lightness = (AD("0.2104542553") * l_) + (AD("0.793617785") * m_) - (AD("0.0040720468") * s_)
+        a         = (AD("1.9779984951") * l_) - (AD("2.4285922050") * m_) + (AD("0.4505937099") * s_)
+        b         = (AD("0.0259040371") * l_) + (AD("0.7827717662") * m_) - (AD("0.8086757660") * s_)
+
+        Color.new(ColorSpace.find(:oklab), [lightness, a, b], xyz_color.alpha)
+      end
+    end
+  end
+end
+
+# Copyright (c) 2025 Durable Programming, LLC. All rights reserved.

data/lib/abachrome/converters/yiq_to_srgb.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+# Abachrome::Converters::YiqToSrgb - YIQ to sRGB color space converter
+#
+# This converter transforms colors from the YIQ color space back to the standard RGB
+# (sRGB) color space using the inverse NTSC transformation matrix. The conversion
+# recombines luminance (Y) and chrominance (I, Q) into RGB components.
+#
+# Key features:
+# - Implements the inverse NTSC YIQ to RGB conversion using matrix transformation
+# - Recombines brightness (Y) and color information (I, Q) into RGB
+# - Maintains alpha channel transparency values during conversion
+# - Uses AbcDecimal arithmetic for precise color science calculations
+# - May produce RGB values outside [0,1] range for out-of-gamut YIQ values
+#
+# The inverse transformation allows colors manipulated in YIQ space (e.g., brightness
+# adjustments on the Y channel) to be converted back to RGB for display.
+
+module Abachrome
+  module Converters
+    class YiqToSrgb
+      # Converts a color from YIQ color space to sRGB color space.
+      # This method applies the inverse NTSC transformation matrix.
+      #
+      # @param yiq_color [Abachrome::Color] A color object in the YIQ color space
+      # @return [Abachrome::Color] A new color object in the sRGB color space
+      # with the same alpha value as the input color
+      def self.convert(yiq_color)
+        y, i, q = yiq_color.coordinates.map { |c| c.to_f }
+
+        # Inverse NTSC YIQ to RGB transformation matrix
+        # R = Y + 0.956I + 0.619Q
+        # G = Y - 0.272I - 0.647Q
+        # B = Y - 1.106I + 1.703Q
+        r = y + (AD("0.9563") * i) + (AD("0.6210") * q)
+        g = y - (AD("0.2721") * i) - (AD("0.6474") * q)
+        b = y - (AD("1.1070") * i) + (AD("1.7046") * q)
+
+        Color.new(
+          ColorSpace.find(:srgb),
+          [r, g, b],
+          yiq_color.alpha
+        )
+      end
+    end
+  end
+end

data/lib/abachrome/gamut/base.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Abachrome
+  module Gamut
+    def self.register(gamut)
+      @gamuts ||= {}
+      @gamuts[gamut.name] = gamut
+    end
+
+    def self.find(name)
+      @gamuts ||= {}
+      @gamuts[name.to_sym] or raise ArgumentError, "Unknown gamut: #{name}"
+    end
+
+    def self.gamuts
+      @gamuts ||= {}
+    end
+
+    class Base
+      attr_reader :name, :primaries, :white_point
+
+      def initialize(name, primaries, white_point)
+        @name = name
+        @primaries = primaries
+        @white_point = white_point
+      end
+
+      # TODO: - make this work properly
+      def contains?(coordinates)
+        x, y, z = coordinates
+        x.between?(0, 1) &&
+          y >= 0 && y <= 1 &&
+          z >= 0 && z <= 1
+      end
+
+      def map(coordinates, method: :clip)
+        case method
+        when :clip
+          clip(coordinates)
+        when :scale
+          scale(coordinates)
+        else
+          raise ArgumentError, "Unknown mapping method: #{method}"
+        end
+      end
+
+      private
+
+      def clip(coordinates)
+        coordinates.map do |c|
+          c.clamp(0, 1)
+        end
+      end
+
+      def scale(coordinates, channels = nil, min = nil, max = nil)
+        min ||= coordinates.min
+        max ||= coordinates.max
+        channels ||= (0..(coordinates.length - 1)).to_a
+
+        scale_factor = if max > 1
+                         1.0 / max
+                       elsif min.negative?
+                         1.0 / (1 - min)
+                       else
+                         1.0
+                       end
+
+        coordinates.each_with_index.map { |c, channel_index| channels.include?(channel_index) ? c * scale_factor : c }
+      end
+    end
+  end
+end
+
+# Copyright (c) 2025 Durable Programming, LLC. All rights reserved.

data/lib/abachrome/gamut/p3.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Abachrome
+  module Gamut
+    class P3 < Base
+      def initialize
+        primaries = {
+          red: [0.680, 0.320],
+          green: [0.265, 0.690],
+          blue: [0.150, 0.060]
+        }
+        super(:p3, primaries, :D65)
+      end
+
+      def contains?(coordinates)
+        r, g, b = coordinates
+        r.between?(0, 1) &&
+          g >= 0 && g <= 1 &&
+          b >= 0 && b <= 1
+      end
+    end
+
+    register(P3.new)
+  end
+end
+
+# Copyright (c) 2025 Durable Programming, LLC. All rights reserved.

data/lib/abachrome/gamut/rec2020.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+lib
+abachrome
+gamut
+rec2020.rb
+
+module Abachrome
+  module Gamut
+    class Rec2020 < Base
+      def initialize
+        primaries = {
+          red: [0.708, 0.292],
+          green: [0.170, 0.797],
+          blue: [0.131, 0.046]
+        }
+        super(:rec2020, primaries, :D65)
+      end
+    end
+
+    register(Rec2020.new)
+  end
+end
+
+# Copyright (c) 2025 Durable Programming, LLC. All rights reserved.

data/lib/abachrome/gamut/srgb.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+# Abachrome::Gamut::SRGB - sRGB color gamut definition and validation
+#
+# This module defines the sRGB color gamut within the Abachrome color manipulation library.
+# The sRGB gamut represents the range of colors that can be displayed on standard monitors
+# and is the default color space for web content and most consumer displays. It uses the
+# D65 white point and specific primary color coordinates that define the boundaries of
+# reproducible colors in the sRGB color space.
+#
+# Key features:
+# - Defines sRGB primary color coordinates for red, green, and blue
+# - Uses D65 illuminant as the white point reference for proper color reproduction
+# - Provides gamut boundary validation to ensure colors fall within displayable ranges
+# - Implements color containment checking for RGB coordinate validation
+# - Automatically registers with the global gamut registry for system-wide access
+# - Serves as the foundation for sRGB color space conversions and display output
+#
+# The sRGB gamut is essential for ensuring colors are properly represented on standard
+# displays and provides the color boundary definitions needed for gamut mapping operations
+# when converting between different color spaces or preparing colors for web and print output.
+
+require_relative "base"
+
+module Abachrome
+  module Gamut
+    class SRGB < Base
+      def initialize
+        primaries = {
+          red: [0.6400, 0.3300],
+          green: [0.3000, 0.6000],
+          blue: [0.1500, 0.0600]
+        }
+        super(:srgb, primaries, :D65)
+      end
+
+      def contains?(coordinates)
+        r, g, b = coordinates
+        r.between?(0, 1) &&
+          g >= 0 && g <= 1 &&
+          b >= 0 && b <= 1
+      end
+    end
+
+    register(SRGB.new)
+  end
+end
+
+# Copyright (c) 2025 Durable Programming, LLC. All rights reserved.

data/lib/abachrome/illuminants/base.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Abachrome
+  module Illuminants
+    class Base
+      class << self
+        def whitepoint
+          raise NotImplementedError, "#{name}#whitepoint must be implemented"
+        end
+
+        def x
+          whitepoint[0]
+        end
+
+        def y
+          whitepoint[1]
+        end
+
+        def z
+          whitepoint[2]
+        end
+
+        def xyz
+          whitepoint
+        end
+
+        def to_s
+          name.split("::").last
+        end
+      end
+    end
+  end
+end
+
+# Copyright (c) 2025 Durable Programming, LLC. All rights reserved.

data/lib/abachrome/illuminants/d50.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Abachrome
+  module Illuminants
+    class D50 < Base
+      def self.x
+        0.96422
+      end
+
+      def self.y
+        1.0
+      end
+
+      def self.z
+        0.82521
+      end
+
+      def self.temperature
+        5003
+      end
+
+      def self.name
+        "D50"
+      end
+
+      def self.description
+        "CIE Standard Illuminant D50 (Horizon Light)"
+      end
+    end
+  end
+end
+
+# Copyright (c) 2025 Durable Programming, LLC. All rights reserved.

data/lib/abachrome/illuminants/d55.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Abachrome
+  module Illuminants
+    class D55 < Base
+      def x
+        0.33243
+      end
+
+      def y
+        0.34744
+      end
+
+      def z
+        0.32013
+      end
+
+      def temperature
+        5503
+      end
+
+      def description
+        "D55 (mid-morning/mid-afternoon daylight)"
+      end
+    end
+  end
+end
+
+# Copyright (c) 2025 Durable Programming, LLC. All rights reserved.