abachrome-float 0.1.6

data/lib/abachrome/color_mixins/to_oklch.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+# Abachrome::ColorMixins::ToOklch - OKLCH color space conversion functionality
+#
+# This mixin provides methods for converting colors to the OKLCH color space, which is a
+# cylindrical representation of the OKLAB color space using lightness, chroma, and hue
+# coordinates. OKLCH offers intuitive color manipulation through its polar coordinate
+# system where hue is represented as an angle and chroma represents colorfulness.
+#
+# Key features:
+# - Convert colors to OKLCH with automatic converter lookup
+# - Both non-destructive (to_oklch) and destructive (to_oklch!) conversion methods
+# - Direct access to OKLCH components (lightness, chroma, hue)
+# - Utility methods for OKLCH 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 OKLCH color space uses three components: L (lightness), C (chroma/colorfulness),
+# and h (hue angle in degrees), providing an intuitive interface for color adjustments
+# that better matches human perception compared to traditional RGB-based color spaces.
+
+module Abachrome
+  module ColorMixins
+    module ToOklch
+      # Converts the current color to the OKLCH color space.
+      #
+      # This method transforms the color into the perceptually uniform OKLCH color space.
+      # If the color is already in OKLCH, it returns itself unchanged. If the color is in
+      # OKLAB, it directly converts from OKLAB to OKLCH. For all other color spaces, it
+      # first converts to OKLAB as an intermediate step, then converts to OKLCH.
+      #
+      # @return [Abachrome::Color] A new Color object in the OKLCH color space
+      def to_oklch
+        return self if color_space.name == :oklch
+
+        if color_space.name == :oklab
+          Converters::OklabToOklch.convert(self)
+        else
+          # For other color spaces, convert to OKLab first
+          oklab_color = to_oklab
+          Converters::OklabToOklch.convert(oklab_color)
+        end
+      end
+
+      # Converts the color to OKLCH color space in-place.
+      # This method transforms the current color to OKLCH color space, modifying
+      # the original object instead of creating a new one. If the color is already
+      # in OKLCH space, no conversion is performed.
+      #
+      # @return [Abachrome::Color] self, allowing for method chaining
+      def to_oklch!
+        unless color_space.name == :oklch
+          oklch_color = to_oklch
+          @color_space = oklch_color.color_space
+          @coordinates = oklch_color.coordinates
+        end
+        self
+      end
+
+      # Returns the lightness component of the color in the OKLCH color space.
+      # This method provides direct access to the first coordinate of the OKLCH
+      # representation of the color, which represents perceptual lightness.
+      #
+      # @return [AbcDecimal] the lightness value in the OKLCH color space,
+      # typically in the range of 0.0 to 1.0, where 0.0 is black and 1.0 is white
+      def lightness
+        to_oklch.coordinates[0]
+      end
+
+      # Returns the chroma value of the color by converting it to the OKLCH color space.
+      # Chroma represents color intensity or saturation in the OKLCH color space.
+      #
+      # @return [AbcDecimal] The chroma value (second coordinate) from the OKLCH color space
+      def chroma
+        to_oklch.coordinates[1]
+      end
+
+      # Returns the hue value of the color in the OKLCH color space.
+      #
+      # @return [AbcDecimal] The hue component of the color in degrees (0-360)
+      # from the OKLCH color space representation.
+      def hue
+        to_oklch.coordinates[2]
+      end
+
+      # Returns the OKLCH coordinates of the color.
+      #
+      # @return [Array<AbcDecimal>] Array of OKLCH coordinates [lightness, chroma, hue] where:
+      # - lightness: perceptual lightness component (0-1)
+      # - chroma: colorfulness/saturation component
+      # - hue: hue angle in degrees (0-360)
+      def oklch_values
+        to_oklch.coordinates
+      end
+
+      # Returns the OKLCH coordinates of the color as an array.
+      #
+      # Converts the current color to OKLCH color space and returns its coordinates
+      # as an array. The OKLCH color space represents colors using Lightness,
+      # Chroma, and Hue components in a perceptually uniform way.
+      #
+      # @return [Array<Numeric>] An array containing the OKLCH coordinates [lightness, chroma, hue]
+      def oklch_array
+        to_oklch.coordinates
+      end
+    end
+  end
+end
+
+# Copyright (c) 2025 Durable Programming, LLC. All rights reserved.

data/lib/abachrome/color_mixins/to_srgb.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+# Abachrome::ColorMixins::ToSrgb - sRGB color space conversion functionality
+#
+# This mixin provides methods for converting colors to the sRGB color space, which is the
+# standard RGB color space used in most displays and web applications. sRGB uses gamma
+# correction to better match human visual perception compared to linear RGB, making it
+# ideal for display purposes and color output in digital media.
+#
+# Key features:
+# - Convert colors to sRGB with automatic converter lookup
+# - Both non-destructive (to_srgb/to_rgb) and destructive (to_srgb!/to_rgb!) conversion methods
+# - Direct access to sRGB components (red, green, blue)
+# - 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 sRGB color space is the default RGB color space for web content and most consumer
+# displays, providing a standardized way to represent colors that will appear consistently
+# across different devices and applications.
+
+require_relative "../converter"
+
+module Abachrome
+  module ColorMixins
+    module ToSrgb
+      # Converts the current color to the sRGB color space.
+      #
+      # If the color is already in the sRGB color space, returns the color instance
+      # unchanged. Otherwise, performs a color space conversion from the current
+      # color space to sRGB.
+      #
+      # @return [Abachrome::Color] A new Color instance in the sRGB color space,
+      # or self if already in sRGB
+      def to_srgb
+        return self if color_space.name == :srgb
+
+        Converter.convert(self, :srgb)
+      end
+
+      # Alias for #to_srgb method.
+      #
+      # @return [Abachrome::Color] The color converted to sRGB color space
+      def to_rgb
+        # assume they mean srgb
+        to_srgb
+      end
+
+      # Converts the color to the sRGB color space, mutating the current object.
+      # If the color is already in sRGB space, this method does nothing.
+      # @return [Abachrome::Color] self for method chaining
+      def to_srgb!
+        unless color_space.name == :srgb
+          srgb_color = to_srgb
+          @color_space = srgb_color.color_space
+          @coordinates = srgb_color.coordinates
+        end
+        self
+      end
+
+      # Converts the current color to sRGB color space in place.
+      # This is an alias for {#to_srgb!} as RGB commonly refers to sRGB
+      # in web and design contexts.
+      #
+      # @return [self] Returns self after converting to sRGB
+      def to_rgb!
+        # assume they mean srgb
+        to_srgb!
+      end
+
+      # Returns the red component of the color in the sRGB color space.
+      #
+      # @return [AbcDecimal] The red component value in the sRGB color space,
+      # normalized between 0 and 1.
+      def red
+        to_srgb.coordinates[0]
+      end
+
+      # Returns the green component of the color in sRGB space.
+      #
+      # This method converts the current color to sRGB color space if needed,
+      # then extracts the green component (second coordinate).
+      #
+      # @return [AbcDecimal] The green component value in the sRGB color space, typically in the range 0-1
+      def green
+        to_srgb.coordinates[1]
+      end
+
+      # Returns the blue component of the color in sRGB color space.
+      #
+      # This method converts the current color to sRGB if needed and
+      # extracts the third coordinate value (blue).
+      #
+      # @return [AbcDecimal] The blue component value in sRGB space, typically in range 0-1
+      def blue
+        to_srgb.coordinates[2]
+      end
+
+      # Returns the RGB color values in the sRGB color space.
+      #
+      # @return [Array<AbcDecimal>] An array of three AbcDecimal values representing
+      # the red, green, and blue color components in the sRGB color space.
+      def srgb_values
+        to_srgb.coordinates
+      end
+
+      # Returns the RGB values of the color as coordinates in the sRGB color space.
+      #
+      # @return [Array<Abachrome::AbcDecimal>] The RGB coordinates (red, green, blue) in sRGB color space
+      def rgb_values
+        to_srgb.coordinates
+      end
+
+      # Returns an array of RGB values (0-255) for this color.
+      #
+      # This method converts the color to sRGB, then scales the component values
+      # from the 0-1 range to the 0-255 range commonly used in RGB color codes.
+      # Values are rounded to the nearest integer and clamped between 0 and 255.
+      #
+      # @return [Array<Integer>] An array of three integers representing the [R, G, B]
+      # values in the 0-255 range
+      def rgb_array
+        to_srgb.coordinates.map { |c| (c * 255).round.clamp(0, 255) }
+      end
+
+      # Returns a hexadecimal representation of this color in sRGB color space.
+      # Converts the color to sRGB, then formats it as a hexadecimal string.
+      #
+      # @return [String] A string in the format "#RRGGBB" where RR, GG, and BB are
+      # the hexadecimal representations of the red, green, and blue components,
+      # each ranging from 00 to FF.
+      # @example
+      # color.rgb_hex #=> "#3a7bc8"
+      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_models/cmyk.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+# Abachrome::ColorModels::CMYK - CMYK color space model utilities
+#
+# This module provides utility methods for the CMYK (Cyan, Magenta, Yellow, Key/Black)
+# color model within the Abachrome color manipulation library. CMYK represents colors
+# using the subtractive color synthesis model used in printing and physical media.
+#
+# Key features:
+# - Subtractive color model (ink on paper, not light)
+# - Four channels: Cyan, Magenta, Yellow, and Key (Black)
+# - Supports Undercolor Removal (UCR) for ink savings
+# - Supports Gray Component Replacement (GCR) for richer blacks
+# - High-precision BigDecimal arithmetic for exact ink percentages
+# - Essential for print media, PDF generation, and pre-press workflows
+#
+# The CMYK model is fundamental for professional printing, where the fourth channel
+# (Black/Key) is added to achieve crisp text and deep shadows that cannot be produced
+# by combining cyan, magenta, and yellow inks alone.
+
+
+module Abachrome
+  module ColorModels
+    class CMYK
+      include Abachrome::ToAbcd
+
+      class << self
+        # Normalizes CMYK color component values to the [0,1] range.
+        #
+        # @param c [Numeric] Cyan component (0-1 or 0-100 for percentages)
+        # @param m [Numeric] Magenta component (0-1 or 0-100 for percentages)
+        # @param y [Numeric] Yellow component (0-1 or 0-100 for percentages)
+        # @param k [Numeric] Key/Black component (0-1 or 0-100 for percentages)
+        # @return [Array<AbcDecimal>] Array of four normalized components as AbcDecimal objects
+        def normalize(c, m, y, k)
+          [c, m, y, k].map do |value|
+            case value
+            when String
+              if value.end_with?("%")
+                value_without_percent = value.chomp("%")
+                value_without_percent.to_f / 100.to_f
+              else
+                value.to_f
+              end
+            when Numeric
+              if value > 1
+                value.to_f / 100.to_f
+              else
+                value.to_f
+              end
+            end
+          end
+        end
+
+        # Converts RGB values to CMYK using the standard naive conversion.
+        # This produces high ink coverage and is generally not recommended for production.
+        #
+        # @param r [Numeric] Red component (0-1)
+        # @param g [Numeric] Green component (0-1)
+        # @param b [Numeric] Blue component (0-1)
+        # @return [Array<AbcDecimal>] Array of [c, m, y, k] values
+        def from_rgb_naive(r, g, b)
+          r = r.to_f
+          g = g.to_f
+          b = b.to_f
+
+          # Simple complementary conversion
+          c = 1.to_f - r
+          m = 1.to_f - g
+          y = 1.to_f - b
+          k = 0.to_f
+
+          [c, m, y, k]
+        end
+
+        # Converts RGB values to CMYK using Undercolor Removal (UCR).
+        # This extracts the gray component to the black (K) channel, reducing ink usage.
+        #
+        # @param r [Numeric] Red component (0-1)
+        # @param g [Numeric] Green component (0-1)
+        # @param b [Numeric] Blue component (0-1)
+        # @param gcr_amount [Numeric] Gray Component Replacement amount (0-1), default 1.0 for full UCR
+        # @return [Array<AbcDecimal>] Array of [c, m, y, k] values
+        def from_rgb_ucr(r, g, b, gcr_amount = 1.0)
+          r = r.to_f
+          g = g.to_f
+          b = b.to_f
+          gcr = gcr_amount.to_f
+
+          # Calculate complementary CMY values
+          c = 1.to_f - r
+          m = 1.to_f - g
+          y = 1.to_f - b
+
+          # Find the minimum (gray component)
+          k = [c, m, y].min * gcr
+
+          # Remove the gray component from CMY if k > 0
+          if k.positive?
+            c -= k
+            m -= k
+            y -= k
+          end
+
+          [c, m, y, k]
+        end
+
+        # Alias for from_rgb_ucr with full GCR (the standard approach).
+        # GCR is essentially the same as UCR but allows control over how much
+        # of the gray component to extract.
+        #
+        # @param r [Numeric] Red component (0-1)
+        # @param g [Numeric] Green component (0-1)
+        # @param b [Numeric] Blue component (0-1)
+        # @param amount [Numeric] Amount of GCR to apply (0-1), default 1.0
+        # @return [Array<AbcDecimal>] Array of [c, m, y, k] values
+        def from_rgb_gcr(r, g, b, amount = 1.0)
+          from_rgb_ucr(r, g, b, amount)
+        end
+
+        # Converts CMYK values back to RGB.
+        # This is a straightforward inverse of the naive RGB→CMY conversion
+        # plus the addition of the black channel.
+        #
+        # @param c [Numeric] Cyan component (0-1)
+        # @param m [Numeric] Magenta component (0-1)
+        # @param y [Numeric] Yellow component (0-1)
+        # @param k [Numeric] Key/Black component (0-1)
+        # @return [Array<AbcDecimal>] Array of [r, g, b] values
+        def to_rgb(c, m, y, k)
+          c = c.to_f
+          m = m.to_f
+          y = y.to_f
+          k = k.to_f
+
+          # Standard CMYK to RGB conversion
+          r = (1.to_f - c) * (1.to_f - k)
+          g = (1.to_f - m) * (1.to_f - k)
+          b = (1.to_f - y) * (1.to_f - k)
+
+          [r, g, b]
+        end
+
+        # Calculates the Total Area Coverage (TAC) for CMYK values.
+        # TAC is the sum of all four ink percentages and is critical in print workflows
+        # to prevent excessive ink that can cause smearing or paper damage.
+        #
+        # @param c [Numeric] Cyan component (0-1)
+        # @param m [Numeric] Magenta component (0-1)
+        # @param y [Numeric] Yellow component (0-1)
+        # @param k [Numeric] Key/Black component (0-1)
+        # @return [AbcDecimal] Total ink coverage as a decimal (0-4, often expressed as 0-400%)
+        def total_area_coverage(c, m, y, k)
+          c.to_f + m.to_f + y.to_f + k.to_f
+        end
+      end
+    end
+  end
+end

data/lib/abachrome/color_models/hsv.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+# Abachrome::ColorModels::HSV - HSV color space model definition
+#
+# This module defines the HSV (Hue, Saturation, Value) color model within the Abachrome
+# color manipulation library. HSV provides an intuitive way to represent colors using
+# cylindrical coordinates where hue represents the color type, saturation represents
+# the intensity or purity of the color, and value represents the brightness.
+#
+# Key features:
+# - Registers the HSV color space with coordinate names [hue, saturation, value]
+# - Validates HSV coordinates to ensure all components are within the [0, 1] range
+# - Uses normalized 0-1 values internally for consistency with other color models
+# - Provides a more intuitive interface for color adjustments compared to RGB
+# - Supports conversion to and from other color spaces through the converter system
+#
+# The HSV model is particularly useful for color picking interfaces and applications
+# where users need to adjust color properties in a way that matches human perception
+# of color relationships. All coordinate values are stored as AbcDecimal objects to
+# maintain precision during color science calculations.
+
+module Abachrome
+  module ColorModels
+    class HSV < Base
+      #
+      # Internally, we use 0..1.0 values for hsv, unlike the standard 0..360, 0..255, 0..255.
+      #
+      # Values can be converted for output.
+      #
+
+      register :hsv, "HSV", %w[hue saturation value]
+
+      # Validates whether the coordinates are valid for the HSV color model.
+      # Each component (hue, saturation, value) must be in the range [0, 1].
+      #
+      # @param coordinates [Array<Numeric>] An array of three values representing
+      # hue (h), saturation (s), and value (v) in the range [0, 1]
+      # @return [Boolean] true if all coordinates are within valid ranges, false otherwise
+      def valid_coordinates?(coordinates)
+        h, s, v = coordinates
+        h.between?(0, 1.0) &&
+          s >= 0 && s <= 1.0 &&
+          v >= 0 && v <= 1.0
+      end
+    end
+  end
+end
+
+# Copyright (c) 2025 Durable Programming, LLC. All rights reserved.

data/lib/abachrome/color_models/lms.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+# Abachrome::ColorModels::Lms - LMS color space model definition
+#
+# This module defines the LMS color model within the Abachrome color manipulation library.
+# LMS represents the response of the three types of cone cells in the human eye (Long, Medium, Short)
+# and serves as an intermediate color space in the OKLAB transformation pipeline. The LMS color space
+# provides a foundation for perceptually uniform color representations by modeling human visual perception
+# at the photoreceptor level.
+#
+# Key features:
+# - Registers the LMS color space with coordinate names [l, m, s]
+# - Represents cone cell responses for Long, Medium, and Short wavelength sensitivity
+# - Serves as intermediate color space for OKLAB and linear RGB conversions
+# - Uses normalized values for consistency with other color models in the library
+# - Maintains high precision through AbcDecimal arithmetic for color transformations
+# - Provides validation for LMS coordinate ranges to ensure valid color representations
+#
+# The LMS model is particularly important in the color science pipeline as it bridges the gap
+# between linear RGB representations and perceptually uniform color spaces like OKLAB, enabling
+# accurate color transformations that better match human visual perception characteristics.
+
+module Abachrome
+  module ColorModels
+    class Lms
+    end
+  end
+end
+
+ColorSpace.register(
+  :lms,
+  "LMS",
+  %w[l m s],
+  nil,
+  []
+)
+
+# Copyright (c) 2025 Durable Programming, LLC. All rights reserved.

data/lib/abachrome/color_models/oklab.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+# Abachrome::ColorModels::Oklab - OKLAB color space model definition
+#
+# This module defines the OKLAB color model within the Abachrome color manipulation library.
+# OKLAB is a perceptually uniform color space designed for better color manipulation and
+# comparison, providing more intuitive lightness adjustments and color blending compared
+# to traditional RGB color spaces.
+#
+# Key features:
+# - Registers the OKLAB color space with coordinate names [lightness, a, b]
+# - Uses L (lightness) ranging from 0 (black) to 1 (white)
+# - Uses a and b components representing green-red and blue-yellow axes respectively
+# - Provides perceptually uniform color space for accurate color science calculations
+# - Serves as an intermediate color space for conversions to OKLCH and other models
+# - Maintains high precision through AbcDecimal arithmetic for color transformations
+#
+# The OKLAB model is particularly useful for color adjustments that need to appear natural
+# to human perception, such as lightness modifications, color blending, and gamut mapping
+# operations where perceptual uniformity is important.
+
+module Abachrome
+  module ColorModels
+    class Oklab
+    end
+  end
+end
+
+ColorSpace.register(
+  :oklab,
+  "Oklab",
+  %w[l a b],
+  nil,
+  ["ok-lab"]
+)
+
+# Copyright (c) 2025 Durable Programming, LLC. All rights reserved.

data/lib/abachrome/color_models/oklch.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+# Abachrome::ColorModels::Oklch - OKLCH color space model definition
+#
+# This module defines the OKLCH color model within the Abachrome color manipulation library.
+# OKLCH is a cylindrical representation of the OKLAB color space using lightness, chroma, and hue
+# coordinates. OKLCH offers intuitive color manipulation through its polar coordinate
+# system where hue is represented as an angle and chroma represents colorfulness.
+#
+# Key features:
+# - Registers the OKLCH color space with coordinate names [lightness, chroma, hue]
+# - Provides conversion utilities between OKLCH and OKLAB color spaces
+# - Uses L (lightness) ranging from 0 (black) to 1 (white)
+# - Uses C (chroma) representing colorfulness intensity starting from 0
+# - Uses h (hue) as an angle in degrees from 0 to 360
+# - Includes normalization methods for proper coordinate ranges
+# - Maintains high precision through AbcDecimal arithmetic for color transformations
+#
+# The OKLCH model is particularly useful for color adjustments that need to appear natural
+# to human perception, such as hue shifts, saturation modifications, and lightness changes
+# where the cylindrical coordinate system provides more intuitive control compared to
+# rectangular color spaces.
+
+module Abachrome
+  module ColorModels
+    class Oklch
+      # Normalizes OKLCH color values to their standard ranges.
+      #
+      # @param l [Numeric] The lightness component, will be clamped to range 0-1
+      # @param c [Numeric] The chroma component, will be clamped to range 0-1
+      # @param h [Numeric] The hue component in degrees, will be normalized to range 0-360
+      # @return [Array<AbcDecimal>] Array containing the normalized [lightness, chroma, hue] values
+      def self.normalize(l, c, h)
+        l = l.to_f
+        c = c.to_f
+        h = h.to_f
+
+        # Normalize hue to 0-360 range
+        h -= 360 while h >= 360
+        h += 360 while h.negative?
+
+        # Normalize lightness and chroma to 0-1 range
+        l = l.clamp(0, 1)
+        c = c.clamp(0, 1)
+
+        [l, c, h]
+      end
+
+      # Converts OKLCH color coordinates to OKLab color coordinates.
+      #
+      # @param l [Numeric] The lightness value in the OKLCH color space
+      # @param c [Numeric] The chroma value in the OKLCH color space
+      # @param h [Numeric] The hue value in degrees in the OKLCH color space
+      # @return [Array<Numeric>] An array containing the OKLab coordinates [l, a, b]
+      def self.to_oklab(l, c, h)
+        # Convert OKLCH to OKLab
+        h_rad = h * Math::PI / 180
+        a = c * Math.cos(h_rad)
+        b = c * Math.sin(h_rad)
+        [l, a, b]
+      end
+
+      # Converts OKLab color coordinates to OKLCH color coordinates.
+      #
+      # @param l [Numeric] The lightness component from OKLab.
+      # @param a [Numeric] The green-red component from OKLab.
+      # @param b [Numeric] The blue-yellow component from OKLab.
+      # @return [Array<Numeric>] An array containing the OKLCH values [l, c, h] where:
+      # - l is the lightness component (unchanged from OKLab)
+      # - c is the chroma component (calculated from a and b)
+      # - h is the hue angle in degrees (0-360)
+      def self.from_oklab(l, a, b)
+        # Convert OKLab to OKLCH
+        c = Math.sqrt((a * a) + (b * b))
+        h = Math.atan2(b, a) * 180 / Math::PI
+        h += 360 if h.negative?
+        [l, c, h]
+      end
+    end
+  end
+end
+
+ColorSpace.register(
+  :oklch,
+  "OKLCh",
+  %w[lightness chroma hue],
+  nil,
+  ["ok-lch"]
+)
+
+# Copyright (c) 2025 Durable Programming, LLC. All rights reserved.

data/lib/abachrome/color_models/rgb.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+# Abachrome::ColorModels::RGB - RGB color space model utilities
+#
+# This module provides utility methods for the RGB color model within the Abachrome
+# color manipulation library. RGB represents colors using red, green, and blue
+# components, which is the most common color model for digital displays and web
+# applications.
+#
+# Key features:
+# - Normalizes RGB component values to the [0, 1] range from various input formats
+# - Handles percentage values (with % suffix) by dividing by 100
+# - Handles 0-255 range values by dividing by 255
+# - Handles 0-1 range values directly without conversion
+# - Supports string and numeric input types for flexible color specification
+# - Maintains high precision through AbcDecimal arithmetic for color calculations
+#
+# The RGB model serves as a foundation for sRGB and linear RGB color spaces,
+# providing the basic coordinate normalization needed for accurate color
+# representation and conversion between different RGB-based color spaces.
+
+module Abachrome
+  module ColorModels
+    class RGB
+      class << self
+        # Normalizes RGB color component values to the [0,1] range.
+        #
+        # @param r [String, Numeric] Red component. If string with % suffix, interpreted as percentage;
+        # if string without suffix or numeric > 1, interpreted as 0-255 range value;
+        # if numeric ≤ 1, used directly.
+        # @param g [String, Numeric] Green component. Same interpretation as red component.
+        # @param b [String, Numeric] Blue component. Same interpretation as red component.
+        # @return [Array<AbcDecimal>] Array of three normalized components as AbcDecimal objects,
+        # each in the range [0,1].
+        def normalize(r, g, b)
+          [r, g, b].map do |value|
+            case value
+            when String
+              if value.end_with?("%")
+                value.chomp("%".to_f) / 100.to_f
+              else
+                value.to_f / 255.to_f
+              end
+            when Numeric
+              if value > 1
+                value.to_f / 255.to_f
+              else
+                value.to_f
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+# Copyright (c) 2025 Durable Programming, LLC. All rights reserved.