pixelart-colors 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 20d3ab72b943a3e9b6cbe0a7f67cf376f6f7a077de3c0456d93a8b2a3e386e0d
+  data.tar.gz: e4bdb8430d7d20337d3e01bd7daa885b01ead91f692af8d6af0a4b53b65c9f8d
+SHA512:
+  metadata.gz: 7d8e890fd954aa76e116a0c9cf8ae27450b6115e0e41091dbcc580dd147cf609f21546acc8aa151b1df249f871e28aacc5173bbbee864e370a6a0e90d5aa8883
+  data.tar.gz: 5f83c8148e7ffb34f7b049481943ee671e3a6bd63bfbd38a43a2e82c6e23fff14e5d29b4823620b22da93474de12b0b8987fe82e38a3273b9b4b05e5a56f2c19

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+### 0.0.1 / 2022-07-09
+
+* Everything is new. First release

data/Manifest.txt

@@ -0,0 +1,13 @@
+CHANGELOG.md
+Manifest.txt
+README.md
+Rakefile
+lib/pixelart/colors.rb
+lib/pixelart/colors/base.rb
+lib/pixelart/colors/color.rb
+lib/pixelart/colors/format.rb
+lib/pixelart/colors/gradient.rb
+lib/pixelart/colors/palette.rb
+lib/pixelart/colors/version.rb
+sandbox/test_colors.rb
+sandbox/test_gradient.rb

data/README.md

@@ -0,0 +1,31 @@
+# Pixel Art (True) Colors
+
+pixelart-colors - helpers to work with true colors as integers; 256 shades for r/g/b (red, green and blue) totaling 16 million colors; incl. hsl, hsv color space converters and more
+
+
+* home  :: [github.com/pixelartexchange/pixelart](https://github.com/pixelartexchange/pixelart)
+* bugs  :: [github.com/pixelartexchange/pixelart/issues](https://github.com/pixelartexchange/pixelart/issues)
+* gem   :: [rubygems.org/gems/pixelart-colors](https://rubygems.org/gems/pixelart-colors)
+* rdoc  :: [rubydoc.info/gems/pixelart](http://rubydoc.info/gems/pixelart-colors)
+
+
+
+##  Usage
+
+To be done
+
+
+
+
+
+
+## License
+
+The scripts are dedicated to the public domain.
+Use it as you please with no restrictions whatsoever.
+
+
+## Questions? Comments?
+
+Post them on the [D.I.Y. Punk (Pixel) Art reddit](https://old.reddit.com/r/DIYPunkArt). Thanks.
+

data/Rakefile

@@ -0,0 +1,28 @@
+require 'hoe'
+require './lib/pixelart/colors/version.rb'
+
+Hoe.spec 'pixelart-colors' do
+
+  self.version = Pixelart::Module::Colors::VERSION
+
+
+  self.summary = "pixelart-colors - helpers to work with true colors as integers; 256 shades for r/g/b (red, green and blue) totaling 16 million colors; incl. hsl, hsv color space converters and more"
+  self.description = summary
+
+  self.urls    = { home: 'https://github.com/pixelartexchange/pixelart' }
+
+  self.author  = 'Gerald Bauer'
+  self.email   = 'wwwmake@googlegroups.com'
+
+  # switch extension to .markdown for gihub formatting
+  self.readme_file  = 'README.md'
+  self.history_file = 'CHANGELOG.md'
+
+  self.extra_deps = []
+
+  self.licenses = ['Public Domain']
+
+  self.spec_extras = {
+    required_ruby_version: '>= 2.3'
+  }
+end

data/lib/pixelart/colors/base.rb

@@ -0,0 +1,28 @@
+
+# bonus / prologue / convenience 3rd party
+# require 'csvreader'   -- add later - why? why not?
+
+
+## stdlib
+require 'pp'
+require 'time'
+require 'date'
+require 'fileutils'
+
+require 'json'
+require 'yaml'
+
+
+
+
+## our own code
+require 'pixelart/colors/version'    # note: let version always go first
+require 'pixelart/colors/color'
+require 'pixelart/colors/format'
+
+require 'pixelart/colors/gradient'
+require 'pixelart/colors/palette'
+
+
+
+puts Pixelart::Module::Colors.banner    # say hello

data/lib/pixelart/colors/color.rb

@@ -0,0 +1,321 @@
+module Pixelart
+
+
+class Color       ## todo/check - change class to module Color - why? why not?
+
+  TRANSPARENT = 0            # rgba(  0,   0,   0,   0)
+  BLACK       = 0xff         # rgba(  0,   0,   0, 255)
+  WHITE       = 0xffffffff   # rgba(255, 255, 255, 255)
+
+
+  def self.parse( color )
+    if color.is_a?( Integer )  ## e.g. assumes rgba or such
+      color ## pass through as is 1:1
+    elsif color.is_a?( Array )  ## assume array of hsl(a) e. g. [180, 0.86, 0.88]
+      from_hsl( *color )
+    elsif color.is_a?( String )
+      if color.downcase == 'transparent'   ## special case for builtin colors
+        TRANSPARENT
+      else
+        ## note: return an Integer !!! (not a Color class or such!!! )
+        from_hex( color )
+      end
+    else
+      raise ArgumentError, "unknown color format; cannot parse - expected rgb hex string e.g. d3d3d3"
+    end
+  end
+
+
+    # Creates a new color using an r, g, b triple and an alpha value.
+    # @param [Integer] r The r-component (0-255)
+    # @param [Integer] g The g-component (0-255)
+    # @param [Integer] b The b-component (0-255)
+    # @param [Integer] a The opacity (0-255)
+    # @return [Integer] The newly constructed color value.
+    def self.rgba(r, g, b, a)
+      r << 24 | g << 16 | b << 8 | a
+    end
+
+    # Creates a new color using an r, g, b triple.
+    # @param [Integer] r The r-component (0-255)
+    # @param [Integer] g The g-component (0-255)
+    # @param [Integer] b The b-component (0-255)
+    # @return [Integer] The newly constructed color value.
+    def self.rgb(r, g, b)
+      r << 24 | g << 16 | b << 8 | 0xff
+    end
+
+
+    # Returns the red-component from the color value.
+    #
+    # @param [Integer] value The color value.
+    # @return [Integer] A value between 0 and MAX.
+    def self.r(value)
+      (value & 0xff000000) >> 24
+    end
+
+    # Returns the green-component from the color value.
+    #
+    # @param [Integer] value The color value.
+    # @return [Integer] A value between 0 and MAX.
+    def self.g(value)
+      (value & 0x00ff0000) >> 16
+    end
+
+    # Returns the blue-component from the color value.
+    #
+    # @param [Integer] value The color value.
+    # @return [Integer] A value between 0 and MAX.
+    def self.b(value)
+      (value & 0x0000ff00) >> 8
+    end
+
+    # Returns the alpha channel value for the color value.
+    #
+    # @param [Integer] value The color value.
+    # @return [Integer] A value between 0 and MAX.
+    def self.a(value)
+      value & 0x000000ff
+    end
+
+
+
+
+    # Returns true if this color is fully opaque.
+    #
+    # @param [Integer] value The color to test.
+    # @return [true, false] True if the alpha channel equals MAX.
+    def self.opaque?(value)
+      a(value) == 0x000000ff
+    end
+
+    # Returns true if this color is fully transparent.
+    #
+    # @param [Integer] value The color to test.
+    # @return [true, false] True if the r, g and b component are equal.
+    def self.grayscale?(value)
+      r(value) == b(value) && b(value) == g(value)
+    end
+
+    # Returns true if this color is fully transparent.
+    #
+    # @param [Integer] value The color to test.
+    # @return [true, false] True if the alpha channel equals 0.
+    def self.transparent?(value)
+      a(value) == 0x00000000
+    end
+
+
+
+  # The regexp to parse 3-digit hex color values.
+  HEX3_COLOR_REGEXP  = /\A(?:#|0x)?([0-9a-f]{3})\z/i
+
+  # The regexp to parse 6- and 8-digit hex color values.
+  HEX6_COLOR_REGEXP  = /\A(?:#|0x)?([0-9a-f]{6})([0-9a-f]{2})?\z/i
+
+
+  def self.from_hex( hex_str )
+    ## Creates a color by converting it from a string in hex notation.
+    ##
+    ## It supports colors with (#rrggbbaa) or without (#rrggbb)
+    ##  alpha channel as well as the 3-digit short format (#rgb)
+    ## for those without. Color strings may include
+    ## the prefix "0x" or "#"".
+    base_color = case hex_str
+                 when HEX3_COLOR_REGEXP
+                   $1.gsub( /([0-9a-f])/i, '\1\1' ).hex << 8
+                 when HEX6_COLOR_REGEXP
+                   $1.hex << 8
+                 else
+                   raise ArgumentError, "Not a valid hex color notation: #{hex_str.inspect}!"
+                 end
+    opacity = $2 ? $2.hex : 0xff
+    base_color | opacity
+  end
+
+    # Returns a string representing this color using hex notation (i.e.
+    # #rrggbbaa).
+    #
+    # @param [Integer] color The color to convert.
+    # @param [Boolean] include_alpha
+    # @return [String] The color in hex notation, starting with a pound sign.
+  def self.to_hex( color, include_alpha: true )
+      include_alpha ? ("#%08x" % color) : ("#%06x" % [color >> 8])
+  end
+
+
+
+    # Creates a new color from an HSL triple.
+    #
+    # This implementation follows the modern convention of 0 degrees hue
+    # indicating red.
+    #
+    # @param [Fixnum] hue The hue component (0-360)
+    # @param [Fixnum] saturation The saturation component (0-1)
+    # @param [Fixnum] lightness The lightness component (0-1)
+    # @param [Fixnum] alpha Defaults to opaque (255).
+    # @return [Integer] The newly constructed color value.
+    # @raise [ArgumentError] if the hsl triple is invalid.
+    # @see https://en.wikipedia.org/wiki/HSL_and_HSV
+
+  def self.from_hsl( hue, saturation, lightness, alpha=255)
+      raise ArgumentError, "Hue #{hue} was not between 0 and 360" unless (0..360).cover?(hue)
+      raise ArgumentError, "Saturation #{saturation} was not between 0 and 1" unless (0..1).cover?(saturation)
+      raise ArgumentError, "Lightness #{lightness} was not between 0 and 1" unless (0..1).cover?(lightness)
+
+      chroma = (1 - (2 * lightness - 1).abs) * saturation
+      rgb    = cylindrical_to_cubic(hue, saturation, lightness, chroma)
+      rgb.map! { |component| ((component + lightness - 0.5 * chroma) * 255).to_i }
+      rgb << alpha
+      rgba(*rgb)
+  end
+
+    # Creates a new color from an HSV triple.
+    #
+    # Create a new color using an HSV (sometimes also called HSB) triple. The
+    # words `value` and `brightness` are used interchangeably and synonymously
+    # in descriptions of this colorspace. This implementation follows the modern
+    # convention of 0 degrees hue indicating red.
+    #
+    # @param [Fixnum] hue The hue component (0-360)
+    # @param [Fixnum] saturation The saturation component (0-1)
+    # @param [Fixnum] value The value (brightness) component (0-1)
+    # @param [Fixnum] alpha Defaults to opaque (255).
+    # @return [Integer] The newly constructed color value.
+    # @raise [ArgumentError] if the hsv triple is invalid.
+    # @see https://en.wikipedia.org/wiki/HSL_and_HSV
+  def self.from_hsv(hue, saturation, value, alpha=255)
+      raise ArgumentError, "Hue must be between 0 and 360" unless (0..360).cover?(hue)
+      raise ArgumentError, "Saturation must be between 0 and 1" unless (0..1).cover?(saturation)
+      raise ArgumentError, "Value/brightness must be between 0 and 1" unless (0..1).cover?(value)
+
+      chroma = value * saturation
+      rgb    = cylindrical_to_cubic(hue, saturation, value, chroma)
+      rgb.map! { |component| ((component + value - chroma) * 255).to_i }
+      rgb << alpha
+      rgba(*rgb)
+    end
+
+    # Convert one HSL or HSV triple and associated chroma to a scaled rgb triple
+    #
+    # This method encapsulates the shared mathematical operations needed to
+    # convert coordinates from a cylindrical colorspace such as HSL or HSV into
+    # coordinates of the RGB colorspace.
+    #
+    # Even though chroma values are derived from the other three coordinates,
+    # the formula for calculating chroma differs for each colorspace.  Since it
+    # is calculated differently for each colorspace, it must be passed in as
+    # a parameter.
+    #
+    # @param [Fixnum] hue The hue-component (0-360)
+    # @param [Fixnum] saturation The saturation-component (0-1)
+    # @param [Fixnum] y_component The y_component can represent either lightness
+    #     or brightness/value (0-1) depending on which scheme (HSV/HSL) is being used.
+    # @param [Fixnum] chroma The associated chroma value.
+    # @return [Array<Fixnum>] A scaled r,g,b triple. Scheme-dependent
+    #    adjustments are still needed to reach the true r,g,b values.
+    # @see https://en.wikipedia.org/wiki/HSL_and_HSV
+    def self.cylindrical_to_cubic(hue, saturation, y_component, chroma)
+      hue_prime = hue.fdiv(60)
+      x = chroma * (1 - (hue_prime % 2 - 1).abs)
+
+      case hue_prime
+      when (0...1) then [chroma, x, 0]
+      when (1...2) then [x, chroma, 0]
+      when (2...3) then [0, chroma, x]
+      when (3...4) then [0, x, chroma]
+      when (4...5) then [x, 0, chroma]
+      when (5..6)  then [chroma, 0, x]
+      end
+    end
+
+
+
+  # Returns an array with the separate HSL components of a color.
+    #
+    # Note: Because this code internally handles colors as Integers for performance
+    # reasons, some rounding  occurs when importing or exporting HSL colors
+    # whose coordinates are float-based.  Because of this rounding, #to_hsl and
+    # #from_hsl may not be perfect inverses.
+    #
+    # This implementation follows the modern convention of 0 degrees hue indicating red.
+    #
+    # @param [Integer] color The color to convert.
+    # @param [Boolean] include_alpha Flag indicates whether a fourth element
+    #     representing alpha channel should be included in the returned array.
+    # @return [Array<Fixnum>[0]] The hue of the color (0-360)
+    # @return [Array<Fixnum>[1]] The saturation of the color (0-1)
+    # @return [Array<Fixnum>[2]] The lightness of the color (0-1)
+    # @return [Array<Fixnum>[3]] Optional fourth element for alpha, included if
+    #     include_alpha=true (0-255)
+    # @see https://en.wikipedia.org/wiki/HSL_and_HSV
+    def self.to_hsl(color, include_alpha: true )
+      hue, chroma, max, min = hue_and_chroma(color)
+      lightness  = 0.5 * (max + min)
+      saturation = chroma.zero? ? 0.0 : chroma.fdiv(1 - (2 * lightness - 1).abs)
+
+      include_alpha ? [hue, saturation, lightness, a(color)] :
+                      [hue, saturation, lightness]
+    end
+
+    # Returns an array with the separate HSV components of a color.
+    #
+    # Note: Because this code internally handles colors as Integers for performance
+    # reasons, some rounding  occurs when importing or exporting HSV colors
+    # whose coordinates are float-based.  Because of this rounding, #to_hsv and
+    # #from_hsv may not be perfect inverses.
+    #
+    # This implementation follows the modern convention of 0 degrees hue
+    # indicating red.
+    #
+    # @param [Integer] color
+    # @param [Boolean] include_alpha Flag indicates whether a fourth element
+    #    representing alpha channel should be included in the returned array.
+    # @return [Array[0]] The hue of the color (0-360)
+    # @return [Array[1]] The saturation of the color (0-1)
+    # @return [Array[2]] The value of the color (0-1)
+    # @return [Array[3]] Optional fourth element for alpha, included if
+    #    include_alpha=true (0-255)
+    # @see https://en.wikipedia.org/wiki/HSL_and_HSV
+    def self.to_hsv(color, include_alpha: true )
+      hue, chroma, max, _ = hue_and_chroma(color)
+      value      = max
+      saturation = chroma.zero? ? 0.0 : chroma.fdiv(value)
+
+      include_alpha ? [hue, saturation, value, a(color)] :
+                      [hue, saturation, value]
+    end
+
+
+
+    # This method encapsulates the logic needed to extract hue and chroma from
+    # a color. This logic is shared by the cylindrical HSV/HSB and HSL
+    # color space models.
+    #
+    # @param [Integer] color.
+    # @return [Fixnum] hue The hue of the color (0-360)
+    # @return [Fixnum] chroma The chroma of the color (0-1)
+    # @return [Fixnum] max The magnitude of the largest scaled rgb component (0-1)
+    # @return [Fixnum] min The magnitude of the smallest scaled rgb component (0-1)
+    # @private
+    def self.hue_and_chroma(color)
+      scaled_rgb = [r(color), g(color), b(color)]
+      scaled_rgb.map! { |component| component.fdiv(255) }
+      min, max = scaled_rgb.minmax
+      chroma   = max - min
+
+      r, g, b   = scaled_rgb
+      hue_prime = chroma.zero? ? 0 : case max
+                                     when r then (g - b).fdiv(chroma)
+                                     when g then (b - r).fdiv(chroma) + 2
+                                     when b then (r - g).fdiv(chroma) + 4
+                                     else 0
+                                     end
+      hue = 60 * hue_prime
+
+      [hue.round, chroma, max, min]
+    end
+end  # class Color
+end  # module Pixelart
+
+

data/lib/pixelart/colors/format.rb

@@ -0,0 +1,77 @@
+
+module Pixelart
+class Color       ## todo/check - change class to module Color - why? why not?
+
+
+  ## known built-in color names
+  def self.build_names
+    names = {
+      '#00000000' => 'TRANSPARENT',
+      '#000000ff' => 'BLACK',
+      '#ffffffff' => 'WHITE',
+    }
+
+    ## auto-add grayscale 1 to 254
+    (1..254).each do |n|
+      hex = "#" + ('%02x' % n)*3
+      hex << "ff"  ## add alpha channel (255)
+      names[ hex ] = "8-BIT GRAYSCALE ##{n}"
+    end
+
+    names
+  end
+
+  NAMES = build_names
+
+
+
+  def self.format( color )
+    rgb = [r(color),
+           g(color),
+           b(color)]
+
+    # rgb in hex (string format)
+    #   note: do NOT include alpha channel for now - why? why not?
+    hex = "#" + rgb.map{|num| '%02x' % num }.join
+
+    hsl = to_hsl( color )
+    hsv = to_hsv( color )
+
+    buf = ''
+    buf << hex
+    buf << " / "
+    buf << "rgb("
+    buf << "%3d " % rgb[0]
+    buf << "%3d " % rgb[1]
+    buf << "%3d)"  % rgb[2]
+    buf << " - "
+    buf << "hsl("
+    buf << "%3d° " % (hsl[0] % 360)
+    buf << "%3d%% " % (hsl[1]*100+0.5).to_i
+    buf << "%3d%%)" % (hsl[2]*100+0.5).to_i
+    buf << " - "
+    buf << "hsv("
+    buf << "%3d° " % (hsv[0] % 360)
+    buf << "%3d%% " % (hsv[1]*100+0.5).to_i
+    buf << "%3d%%)" % (hsv[2]*100+0.5).to_i
+
+    alpha = a(color)
+    if alpha != 255
+      buf << " - α(%3d%%)" % (alpha*100/255+0.5).to_i
+    else
+      buf << "          "  ## add empty for 255 (full opacity)
+    end
+
+    ## note: add alpha channel to hex
+    alpha_hex = '%02x' % alpha
+    name = NAMES[ hex+alpha_hex ]
+    buf << " - #{name}"  if name
+
+    buf
+  end
+  class << self
+    alias_method :fmt, :format
+  end
+
+end  # class Color
+end  # module Pixelart

data/lib/pixelart/colors/gradient.rb

@@ -0,0 +1,106 @@
+
+## inspired / helped by
+##  https://en.wikipedia.org/wiki/List_of_software_palettes#Color_gradient_palettes
+##  https://github.com/mistic100/tinygradient
+##   https://mistic100.github.io/tinygradient/
+##   https://bsouthga.dev/posts/color-gradients-with-python
+
+
+module Pixelart
+
+class Gradient
+
+  def initialize( *stops )
+    ## note:  convert stop colors to rgb triplets e.g.
+    ##         from #ffffff to [255,255,255]
+    ##              #000000 to [0,0,0]  etc.
+    @stops = stops.map do |stop|
+               stop = Color.parse( stop )
+               [Color.r(stop), Color.g(stop), Color.b(stop)]
+             end
+  end
+
+
+  def colors( steps )
+    segments = @stops.size - 1
+
+    ## note: gradient will include start (first)
+    ##   AND stop color (last) - stop color is NOT excluded for now!!
+    if segments == 1
+       start = @stops[0]
+       stop  = @stops[1]
+
+       gradient = linear_gradient( start, stop, steps,
+                                   include_stop: true )
+    else
+      steps_per_segment, mod = steps.divmod( segments )
+      raise ArgumentError, "steps (#{steps}) must be divisible by # of segments (#{segments}); expected mod of 0 but got #{mod}"   if mod != 0
+
+      gradient = []
+      segments.times do |segment|
+        start = @stops[segment]
+        stop  = @stops[segment+1]
+        include_stop =  (segment == segments-1)  ## note: only include stop if last segment!!
+
+        # print "  segment #{segment+1}/#{segments} #{steps_per_segment} color(s) - "
+        # print "  start: #{start.inspect}  "
+        # print  include_stop ? 'include' : 'exclude'
+        # print " stop:  #{stop.inspect}"
+        # print "\n"
+
+        gradient += linear_gradient( start, stop, steps_per_segment,
+                                     include_stop: include_stop )
+      end
+    end
+
+    ## convert to color (Integer)
+    gradient.map do |color|
+      Color.rgb( *color )
+    end
+ end
+
+
+
+ def interpolate( start, stop, steps, n )
+   ## note: n - expected to start with 1,2,3,etc.
+   color = []
+   3.times do |i|
+     stepize = Float(stop[i] - start[i]) / Float(steps-1)
+     value = stepize * n
+     ## convert back to Integer from Float
+     ##   add 0.5 for rounding up (starting with 0.5) - why? why not?
+     value = (value+0.5).to_i
+     value = start[i] + value
+
+     color << value
+   end
+   color
+ end
+
+
+ def linear_gradient( start, stop, steps,
+                      include_stop: true )
+
+  gradient = [start]  ## auto-add start color (first color in gradient)
+
+  if include_stop
+    1.upto( steps-2 ).each do |n|  ## sub two (-2), that is, start and stop color
+      gradient << interpolate( start, stop, steps, n )
+    end
+    # note: use original passed in stop color (should match calculated)
+    gradient << stop
+  else
+    1.upto( steps-1 ).each do |n|  ## sub one (-1), that is, start color only
+      ## note: add one (+1) to steps because stop color gets excluded (not included)!!
+      gradient << interpolate( start, stop, steps+1, n )
+    end
+  end
+
+  gradient
+end
+
+
+
+end  # class Gradient
+end  # module Pixelart
+

data/lib/pixelart/colors/palette.rb

@@ -0,0 +1,72 @@
+module Pixelart
+
+
+class Palette8bit     # or use Palette256 alias?
+                      ##  todo/check: change class Palette8Bit to Module (like Class) - why? why not?
+
+  ## auto-add grayscale 0 to 255
+  ##  e.g. rgb(0,0,0)
+  ##       rgb(1,1,1)
+  ##       rgb(2,2,2)
+  ##       ...
+  ##       rgb(255,255,255)
+  GRAYSCALE = (0..255).map { |n| Color.rgb( n, n, n ) }
+
+
+   ## 8x32 gradient color stops
+   ##   see https://en.wikipedia.org/wiki/List_of_software_palettes#Color_gradient_palettes
+
+  SEPIA_STOPS = [
+    ['080400', '262117'],
+    ['272218', '453E2F'],
+    ['463F30', '645C48'],
+    ['655D48', '837A60'],
+
+    ['847A60', 'A29778'],
+    ['A39878', 'C1B590'],
+    ['C2B691', 'E0D2A8'],
+    ['E1D3A9', 'FEEFBF'],
+  ]
+
+  BLUE_STOPS = [
+    ['000000', '001F3E'],
+    ['002040', '003F7E'],
+    ['004080', '005FBD'],
+    ['0060BF', '007FFD'],
+
+    ['0080FF', '009FFF'],
+    ['00A0FF', '00BFFF'],
+    ['00C0FF', '00DFFF'],
+    ['00E0FF', '00FEFF'],
+  ]
+
+  FALSE_STOPS = [
+    ['FF00FF', '6400FF'],
+    ['5F00FF', '003CFF'],
+    ['0041FF', '00DCFF'],
+    ['00E1FF', '00FF82'],
+
+    ['00FF7D', '1EFF00'],
+    ['23FF00', 'BEFF00'],
+    ['C3FF00', 'FFA000'],
+    ['FF9B00', 'FF0000'],
+  ]
+
+
+  def self.build_palette( gradients )
+    colors_per_gradient, mod = 256.divmod( gradients.size )
+    raise ArgumentError, "8bit palette - 256 must be divisible by # of gradients (#{gradients.size}; expected mod of 0 but got #{mod}"   if mod != 0
+
+    colors = []
+    gradients.each do |stops|
+      colors += Gradient.new( *stops ).colors( colors_per_gradient )
+    end
+    colors
+  end
+
+  SEPIA     = build_palette( SEPIA_STOPS )
+  BLUE      = build_palette( BLUE_STOPS )
+  FALSE     = build_palette( FALSE_STOPS )
+end  # class Palette8bit
+end # module Pixelart
+

data/lib/pixelart/colors/version.rb

@@ -0,0 +1,25 @@
+
+module Pixelart
+module Module
+module Colors
+  MAJOR = 0
+  MINOR = 1
+  PATCH = 0
+  VERSION = [MAJOR,MINOR,PATCH].join('.')
+
+  def self.version
+    VERSION
+  end
+
+  def self.banner
+    "pixelart-colors/#{VERSION} on Ruby #{RUBY_VERSION} (#{RUBY_RELEASE_DATE}) [#{RUBY_PLATFORM}] in (#{root})"
+  end
+
+  def self.root
+    File.expand_path( File.dirname(File.dirname(File.dirname(File.dirname(__FILE__)))) )
+  end
+
+end # module Colors
+end # module Module
+end # module Pixelart
+

data/lib/pixelart/colors.rb

@@ -0,0 +1,22 @@
+
+## our own code (without "top-level" shortcuts e.g. "modular version")
+require 'pixelart/colors/base'   # aka "strict(er)" version
+
+
+
+##########
+#  add some spelling convenience variants
+PixelArt = Pixelart
+
+module Pixelart
+  Palette256 = Palette8Bit = Palette8bit
+end
+
+
+
+###
+#  add convenience top-level shortcuts / aliases
+#    make Image, Color, Palette8bit, etc top-level
+include Pixelart
+
+

data/sandbox/test_colors.rb

@@ -0,0 +1,28 @@
+###
+#  to run use
+#     ruby -I ./lib sandbox/test_colors.rb
+
+
+require 'pixelart/colors/base'
+
+colors = {'transparent' => Pixelart::Color::TRANSPARENT,
+          'black' => Pixelart::Color::BLACK,
+          'white' => Pixelart::Color::WHITE,
+          'red'    =>  0xff0000ff,
+          'yellow' =>  0xffff00ff,   # r(ed) + g(reen) = yellow
+         }
+
+
+colors.each do |name,color|
+  puts "==> #{name} - #{color}"
+  print "  transparent? "; pp Pixelart::Color.transparent?( color )
+  print "  opaque? "; pp Pixelart::Color.opaque?( color )
+
+  print "  to_hex: "; pp Pixelart::Color.to_hex( color )
+  print "  to_hsl: "; pp Pixelart::Color.to_hsl( color )
+  print "  to_hsv: "; pp Pixelart::Color.to_hsv( color )
+  print "  "; puts Pixelart::Color.format( color )
+end
+
+
+puts "bye"

data/sandbox/test_gradient.rb

@@ -0,0 +1,62 @@
+###
+#  to run use
+#     ruby -I ./lib sandbox/test_gradient.rb
+
+
+require 'pixelart/colors/base'
+
+
+gradient = Pixelart::Gradient.new( '000000', 'ffffff' )
+# gradient = Pixelart::Gradient.new(  'ffffff', '000000' )
+
+pp colors = gradient.colors( 256 )   ## 256 steps
+puts "---"
+pp colors.map { |color| Pixelart::Color.format( color ) }
+
+puts
+puts "---"
+pp colors = gradient.colors( 10 )    ## 10 steps
+puts "---"
+pp colors.map { |color| Pixelart::Color.format( color ) }
+
+
+
+gradient = Pixelart::Gradient.new( '000000',
+                                   '050505',
+                                   '0a0a0a', '0e0e0e'
+                                  )
+puts
+puts "---"
+pp colors = gradient.colors( 15 )   ## 15 steps (3x5)
+puts "---"
+pp colors.map { |color| Pixelart::Color.format( color ) }
+
+
+
+####################
+# https://uigradients.com/#Instagram
+
+uigradients = {
+  'instagram'       => ['833ab4',
+                        'fd1d1d', 'fcb045'],
+  'flare'           => ['f12711', 'f5af19'],
+  'terminal'        => ['000000', '0f9b0f'],
+  'the_blue_lagoon' => ['43c6ac', '191654'],
+  'ibiza_sunset'    => ['ee0979', 'ff6a00'],
+  'superman'        => ['0099f7', 'f11712'],
+  'christmas'       => ['2f7336', 'aa3a38'],
+  'dark_knight'     => ['ba8b02', '181818'],
+  'ukraine'         => ['004ff9', 'fff94c'],
+}
+
+
+
+uigradients.each do |name, stops|
+  puts
+  puts "==> #{name}:"
+  gradient = Pixelart::Gradient.new( *stops )
+  colors = gradient.colors( 256 )
+  pp colors.map { |color| Pixelart::Color.format( color ) }
+end
+
+puts "bye"

metadata

@@ -0,0 +1,98 @@
+--- !ruby/object:Gem::Specification
+name: pixelart-colors
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Gerald Bauer
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2022-07-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7'
+- !ruby/object:Gem::Dependency
+  name: hoe
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+description: pixelart-colors - helpers to work with true colors as integers; 256 shades
+  for r/g/b (red, green and blue) totaling 16 million colors; incl. hsl, hsv color
+  space converters and more
+email: wwwmake@googlegroups.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- CHANGELOG.md
+- Manifest.txt
+- README.md
+files:
+- CHANGELOG.md
+- Manifest.txt
+- README.md
+- Rakefile
+- lib/pixelart/colors.rb
+- lib/pixelart/colors/base.rb
+- lib/pixelart/colors/color.rb
+- lib/pixelart/colors/format.rb
+- lib/pixelart/colors/gradient.rb
+- lib/pixelart/colors/palette.rb
+- lib/pixelart/colors/version.rb
+- sandbox/test_colors.rb
+- sandbox/test_gradient.rb
+homepage: https://github.com/pixelartexchange/pixelart
+licenses:
+- Public Domain
+metadata: {}
+post_install_message:
+rdoc_options:
+- "--main"
+- README.md
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.7
+signing_key:
+specification_version: 4
+summary: pixelart-colors - helpers to work with true colors as integers; 256 shades
+  for r/g/b (red, green and blue) totaling 16 million colors; incl. hsl, hsv color
+  space converters and more
+test_files: []