ascii_pngfy 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1d0d17138de3a7998ba69e9cdb8ddb45bc4b0aa259f570b5b76e3f32824512b0
+  data.tar.gz: '08a2046403c7c76e8d0d150224d3ce1df4776539be57b8a0a56cdc16930ceab3'
+SHA512:
+  metadata.gz: f4d7bb12da4c527081fa049e940e3af6e98333ff2850fe796371a6465579f8586409d27b157547abdf9daedcd48ba087d2afba3fe022c159ac42b5a2a4185d4b
+  data.tar.gz: 2345644e3d1f5bf09dbf0f366743dacd555943e6b8e5cbd72e3db9fddb1a5f96fdc491e01e1d7cdd9b4b3990d9ce5568b30b6bfddfce1d60f26bc207e285394e

data/lib/ascii_pngfy.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+# Reponsibilities
+#   - Top level namespace that contains all AsciiPngfy
+#     sub-namespaces and general constants
+#   - Requires all files needed to use the AsciiPngfy Gem
+module AsciiPngfy
+  MAX_RESULT_PNG_IMAGE_WIDTH = 3840
+  MAX_RESULT_PNG_IMAGE_HEIGHT = 2160
+  GLYPH_DESIGN_WIDTH = 5
+  GLYPH_DESIGN_HEIGHT = 9
+  SUPPORTED_ASCII_CODES_WITHOUT_NEWLINE_RANGE = (32..126).freeze
+  SUPPORTED_ASCII_CODES_WITHOUT_NEWLINE = SUPPORTED_ASCII_CODES_WITHOUT_NEWLINE_RANGE.to_a.freeze
+  SUPPORTED_ASCII_CODES = ([10] + SUPPORTED_ASCII_CODES_WITHOUT_NEWLINE).freeze
+  SUPPORTED_ASCII_CHARACTERS = SUPPORTED_ASCII_CODES.map(&:chr).freeze
+end
+
+require 'ascii_pngfy/pngfyer'
+
+require 'ascii_pngfy/exceptions'
+
+require 'ascii_pngfy/settings'
+require 'ascii_pngfy/settings/settings_snapshot'
+require 'ascii_pngfy/settings/setable_getable_settings'
+
+require 'ascii_pngfy/settings/setable_getable'
+require 'ascii_pngfy/settings/color_setting'
+require 'ascii_pngfy/settings/font_height_setting'
+require 'ascii_pngfy/settings/horizontal_spacing_setting'
+require 'ascii_pngfy/settings/vertical_spacing_setting'
+require 'ascii_pngfy/settings/text_setting'
+
+require 'ascii_pngfy/vec2i'
+require 'ascii_pngfy/aabb'
+require 'ascii_pngfy/rendering_rules'
+require 'ascii_pngfy/settings_renderer'
+
+require 'ascii_pngfy/glyphs'
+require 'ascii_pngfy/color_rgba'
+require 'ascii_pngfy/result'

data/lib/ascii_pngfy/aabb.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module AsciiPngfy
+  # Reponsibilities
+  #   - Represents an axis aligned bounding box through a minimum and
+  #     maximum coordinate pair
+  #   - Public getters for the min and max coordinate pair
+  #   - Provides a way to iterate all the pixel coordinates in
+  #     the respective bounding box with and without the pixel index
+  #
+  #     This pixel index follows the conventions used for the glyph
+  #     design string where the index increases based on the iterated
+  #     pixel from:
+  #       - topmost row to bottommost row
+  #       - leftmost pixel to rightmost pixel for each of these rows
+  class AABB
+    attr_reader(:min, :max)
+
+    def initialize(min_x, min_y, max_x, max_y)
+      self.min = Vec2i.new(min_x, min_y)
+      self.max = Vec2i.new(max_x, max_y)
+    end
+
+    def each_pixel(&yielder)
+      min.y.upto(max.y) do |pixel_y|
+        min.x.upto(max.x) do |pixel_x|
+          yielder.call(pixel_x, pixel_y)
+        end
+      end
+    end
+
+    def each_pixel_with_index(&yielder)
+      pixel_index = 0
+      each_pixel do |pixel_x, pixel_y|
+        yielder.call(pixel_x, pixel_y, pixel_index)
+
+        pixel_index += 1
+      end
+    end
+
+    def to_s
+      "min#{min} max#{max}"
+    end
+
+    private
+
+    attr_writer(:min, :max)
+  end
+end

data/lib/ascii_pngfy/color_rgba.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module AsciiPngfy
+  # Reponsibilities
+  #   - Provides RGBA color handling and validation
+  class ColorRGBA
+    VALID_RGBA_COLOR_RANGE = (0..255).freeze
+    attr_reader(:red, :green, :blue, :alpha)
+
+    def initialize(red, green, blue, alpha)
+      self.red = red
+      self.green = green
+      self.blue = blue
+      self.alpha = alpha
+    end
+
+    def red=(new_red)
+      @red = validate_color_value(new_red, :red)
+    end
+
+    def green=(new_green)
+      @green = validate_color_value(new_green, :green)
+    end
+
+    def blue=(new_blue)
+      @blue = validate_color_value(new_blue, :blue)
+    end
+
+    def alpha=(new_alpha)
+      @alpha = validate_color_value(new_alpha, :alpha)
+    end
+
+    def ==(other)
+      other.red == red &&
+        other.green == green &&
+        other.blue == blue &&
+        other.alpha == alpha
+    end
+
+    private
+
+    def validate_color_value(color_value, color_component)
+      return color_value if valid_color_value?(color_value)
+
+      error_message = String.new
+      error_message << "#{color_value.inspect} is not a valid #{color_component} color component value. "
+      error_message << "Must be an Integer in the range (#{VALID_RGBA_COLOR_RANGE})."
+
+      raise Exceptions::InvalidRGBAColorValueError, error_message
+    end
+
+    def valid_color_value?(color_value)
+      color_value.is_a?(Integer) && VALID_RGBA_COLOR_RANGE.cover?(color_value)
+    end
+  end
+end

data/lib/ascii_pngfy/exceptions.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module AsciiPngfy
+  # Provides a custom AsciiPngfy Exceptions hierarchy
+  module Exceptions
+    # Base class to classify AsciiPngfy errors under StandardError
+    class AsciiPngfyError < StandardError; end
+
+    class InvalidRGBAColorValueError < AsciiPngfyError; end
+
+    class InvalidFontHeightError < AsciiPngfyError; end
+
+    class InvalidSpacingError < AsciiPngfyError; end
+
+    class InvalidHorizontalSpacingError < InvalidSpacingError; end
+
+    class InvalidVerticalSpacingError < InvalidSpacingError; end
+
+    class InvalidReplacementTextError < AsciiPngfyError; end
+
+    class InvalidCharacterError < AsciiPngfyError; end
+
+    class EmptyTextError < AsciiPngfyError; end
+
+    class TextLineTooLongError < AsciiPngfyError; end
+
+    class TooManyTextLinesError < AsciiPngfyError; end
+  end
+end

data/lib/ascii_pngfy/glyphs.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module AsciiPngfy
+  # Reponsibilities
+  #   - Provides pixel plotting designs for all supported non-control
+  #     ASCII characters
+  #   - Decides which design character, '.' or '#', represents the
+  #     font layer or the background layer
+  # rubocop: disable Metrics/ModuleLength
+  module Glyphs
+    DESIGNS = {
+      ' ' => '.............................................',
+      '!' => '..#....#....#....#....#.........#............',
+      '"' => '.#.#..#.#..#.#...............................',
+      '#' => '......#.#.#####.#.#..#.#.#####.#.#...........',
+      '$' => '..#...#####.#...###...#.#####...#............',
+      '%' => '#...##...#...#...#...#...#...##...#..........',
+      '&' => '.##..#..#.#..#..#####..#.#..#..##.#..........',
+      "'" => '..#....#....#................................',
+      '(' => '...#...#....#....#....#....#.....#...........',
+      ')' => '..#.....#....#....#....#....#...#............',
+      '*' => '.......#..#.#.#.###.#.#.#..#.................',
+      '+' => '.......#....#..#####..#....#.................',
+      ',' => '...........................#....#...#........',
+      '-' => '...............#####.........................',
+      '.' => '...........................#....#............',
+      '/' => '....#....#...#...#...#...#....#..............',
+      '0' => '.###.#...##..###.#.###..##...#.###...........',
+      '1' => '..#...##....#....#....#....#..#####..........',
+      '2' => '.###.#...#....#...#...#...#...#####..........',
+      '3' => '.###.#...#....#.###.....##...#.###...........',
+      '4' => '.#..#.#..##...######....#....#....#..........',
+      '5' => '######....#....####.....##...#.###...........',
+      '6' => '.###.#....#....####.#...##...#.###...........',
+      '7' => '#####....#....#...#...#....#....#............',
+      '8' => '.###.#...##...#.###.#...##...#.###...........',
+      '9' => '.###.#...##...#.####....##...#.###...........',
+      ':' => '.......#....#..............#....#............',
+      ';' => '.......#....#..............#....#...#........',
+      '<' => '........##.##..#.....##.....##...............',
+      '=' => '..........#####.....#####....................',
+      '>' => '.....##.....##.....#..##.##..................',
+      '?' => '.###.#...#....#...#...#.........#............',
+      '@' => '.###.#..###.#.##.#.##..###.....###...........',
+      'A' => '.###.#...##...##...#######...##...#..........',
+      'B' => '####.#...##...#####.#...##...#####...........',
+      'C' => '.###.#...##....#....#....#...#.###...........',
+      'D' => '####.#...##...##...##...##...#####...........',
+      'E' => '######....#....####.#....#....#####..........',
+      'F' => '######....#....####.#....#....#..............',
+      'G' => '.###.#...##....#.####...##...#.###...........',
+      'H' => '#...##...##...#######...##...##...#..........',
+      'I' => '#####..#....#....#....#....#..#####..........',
+      'J' => '....#....#....#....##...##...#.###...........',
+      'K' => '#...##..#.#.#..##...#.#..#..#.#...#..........',
+      'L' => '#....#....#....#....#....#....#####..........',
+      'M' => '#...###.###.#.##...##...##...##...#..........',
+      'N' => '#...##...###..##.#.##..###...##...#..........',
+      'O' => '.###.#...##...##...##...##...#.###...........',
+      'P' => '####.#...##...#####.#....#....#..............',
+      'Q' => '.###.#...##...##...##...##...#.###....##.....',
+      'R' => '####.#...##...#####.#...##...##...#..........',
+      'S' => '.###.#...##.....###.....##...#.###...........',
+      'T' => '#####..#....#....#....#....#....#............',
+      'U' => '#...##...##...##...##...##...#.###...........',
+      'V' => '#...##...##...##...#.#.#..#.#...#............',
+      'W' => '#...##...##...##...##.#.###.###...#..........',
+      'X' => '#...##...#.#.#...#...#.#.#...##...#..........',
+      'Y' => '#...##...#.#.#...#....#....#....#............',
+      'Z' => '#####....#...#...#...#...#....#####..........',
+      '[' => '..###..#....#....#....#....#....###..........',
+      '\\' => '#....#.....#.....#.....#.....#....#..........',
+      ']' => '###....#....#....#....#....#..###............',
+      '^' => '..#...#.#.#...#..............................',
+      '_' => '..............................#####..........',
+      '`' => '.#.....#.....................................',
+      'a' => '...........#####...##...##...#.####..........',
+      'b' => '#....#....####.#...##...##...#####...........',
+      'c' => '...........###.#...##....#...#.###...........',
+      'd' => '....#....#.#####...##...##...#.####..........',
+      'e' => '...........###.#...#######.....###...........',
+      'f' => '..##..#..#.#...####..#....#....#.............',
+      'g' => '...........#####...##...##...#.####....#.###.',
+      'h' => '#....#....####.#...##...##...##...#..........',
+      'i' => '..#........##....#....#....#..#####..........',
+      'j' => '....#........##....#....#....#....##...#.###.',
+      'k' => '#....#....#...##..#.###..#..#.#...#..........',
+      'l' => '##....#....#....#....#....#.....###..........',
+      'm' => '..........####.#.#.##.#.##.#.##.#.#..........',
+      'n' => '..........####.#...##...##...##...#..........',
+      'o' => '...........###.#...##...##...#.###...........',
+      'p' => '..........####.#...##...##...#####.#....#....',
+      'q' => '...........#####...##...##...#.####....#....#',
+      'r' => '..........#.##.##..###..##....#..............',
+      's' => '...........#####.....###.....#####...........',
+      't' => '.#....#...####..#....#....#.....###..........',
+      'u' => '..........#...##...##...##...#.####..........',
+      'v' => '..........#...##...##...#.#.#...#............',
+      'w' => '..........#...##...##.#.##.#.#.#.#...........',
+      'x' => '..........#...#.#.#...#...#.#.#...#..........',
+      'y' => '..........#...##...##...##...#.####....#.###.',
+      'z' => '..........#####...#...#...#...#####..........',
+      '{' => '...#...#....#...#.....#....#.....#...........',
+      '|' => '..#....#....#....#....#....#....#............',
+      '}' => '.#.....#....#.....#...#....#...#.............',
+      '~' => '................#..##.##.....................'
+    }.freeze
+
+    def self.font_layer_design_character?(some_design_character)
+      some_design_character == '#'
+    end
+
+    def self.background_layer_design_character?(some_design_character)
+      some_design_character == '.'
+    end
+  end
+  # rubocop: enable Metrics/ModuleLength
+end

data/lib/ascii_pngfy/pngfyer.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module AsciiPngfy
+  # Reponsibilities
+  #   - Provide the complete interface of this gem dynamically
+  #     in order to force the interface of the Settings onto the caller
+  #   - Orchestrates the Settings and the SettingsRenderer
+  class Pngfyer
+    def initialize(use_glyph_designs: true)
+      self.settings_renderer = SettingsRenderer.new(use_glyph_designs: use_glyph_designs)
+      self.settings = Settings::SetableGetableSettings.new
+    end
+
+    def respond_to_missing?(method_name, _)
+      setter?(method_name) || super
+    end
+
+    def method_missing(method_name, *arguments)
+      # forward only set_* calls to the settings so that the respective setting
+      # can enforce it's interface and any unsupported setting setters results
+      # in an undefined method error
+      if setter?(method_name)
+        setting_call = method_name
+        settings.public_send(setting_call, *arguments)
+      else
+        super
+      end
+    end
+
+    def pngfy
+      settings_snapshot = settings.snapshot
+      settings_renderer.render_result(settings_snapshot)
+    end
+
+    private
+
+    attr_accessor(:settings, :settings_renderer)
+
+    def setter?(method_name)
+      method_name.start_with?('set_')
+    end
+  end
+end

data/lib/ascii_pngfy/rendering_rules.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+module AsciiPngfy
+  # Reponsibilities
+  #   - The reason for this particulare interface with singleton methods
+  #     at this point, is to avoid coupling between the settings themselves
+  #     and because the architecture is about to change in terms of the
+  #     current implementation of the Settings
+  #
+  #   - Provide a single point of reference for all computations that
+  #     contribute to the renderer result of the #pngfy process
+  #
+  #   - Computations based on setting values such as color;
+  #     font height; spacing and text
+  #
+  #   - General enough so that any settings related context can
+  #     use this functionality
+  # rubocop: disable Metrics/ModuleLength
+  module RenderingRules
+    def self.text_lines(text)
+      text.split("\n", -1)
+    end
+
+    def self.longest_text_line(text)
+      text_lines(text).max_by(&:length)
+    end
+
+    def self.png_width(settings, override_text = nil)
+      use_text = override_text || settings.text
+
+      longest_text_line_length = longest_text_line(use_text).length
+      horizontal_spacing_count = longest_text_line_length - 1
+
+      (longest_text_line_length * GLYPH_DESIGN_WIDTH) + (horizontal_spacing_count * settings.horizontal_spacing)
+    end
+
+    def self.png_height(settings, override_text = nil)
+      use_text = override_text || settings.text
+
+      text_line_count = text_lines(use_text).size
+      vertical_spacing_count = text_line_count - 1
+
+      (text_line_count * GLYPH_DESIGN_HEIGHT) + (vertical_spacing_count * settings.vertical_spacing)
+    end
+
+    def self.font_multiplier(settings)
+      settings.font_height / GLYPH_DESIGN_HEIGHT
+    end
+
+    def self.render_width(settings)
+      png_width(settings) * font_multiplier(settings)
+    end
+
+    def self.render_height(settings)
+      png_height(settings) * font_multiplier(settings)
+    end
+
+    def self.text_lines_characters(settings)
+      text_lines(settings.text).map(&:chars)
+    end
+
+    def self.font_region(settings, character_column_index, character_row_index)
+      font_region_top_left_x = character_column_index * (settings.horizontal_spacing + GLYPH_DESIGN_WIDTH)
+      font_region_top_left_y = character_row_index * (settings.vertical_spacing + GLYPH_DESIGN_HEIGHT)
+      font_region_bottom_right_x = font_region_top_left_x + (GLYPH_DESIGN_WIDTH - 1)
+      font_region_bottom_right_y = font_region_top_left_y + (GLYPH_DESIGN_HEIGHT - 1)
+
+      AABB.new(
+        font_region_top_left_x,
+        font_region_top_left_y,
+        font_region_bottom_right_x,
+        font_region_bottom_right_y
+      )
+    end
+
+    def self.each_font_region_with_associated_character(settings, &yielder)
+      text_lines_characters(settings).each_with_index do |line_characters, row_index|
+        line_characters.each_with_index do |character, column_index|
+          font_region = font_region(settings, column_index, row_index)
+
+          yielder.call(font_region, character)
+        end
+      end
+    end
+
+    def self.each_font_region(settings, &yielder)
+      each_font_region_with_associated_character(settings) do |font_region, _font_region_character|
+        yielder.call(font_region)
+      end
+    end
+
+    def self.color_rgba_to_chunky_png_integer(color_rgba)
+      ChunkyPNG::Color.rgba(
+        color_rgba.red,
+        color_rgba.green,
+        color_rgba.blue,
+        color_rgba.alpha
+      )
+    end
+
+    def self.straight_alpha_composite_color_value(over_component, over_alpha, under_component, under_alpha)
+      # over refers to the top layer, i.e. the font layer
+      ca = over_component
+      aa = over_alpha.fdiv(255)
+
+      # under refers to the bottom layer, i.e. the background layer
+      cb = under_component
+      ab = under_alpha.fdiv(255)
+
+      # return alpha composited color component as integer in range 0..255
+      # avoid divisions by zero
+      numerator = (ca * aa + cb * ab * (1 - aa))
+      denumerator = (aa + ab * (1 - aa))
+
+      return 0 if denumerator.zero? || numerator.zero?
+
+      (numerator / denumerator).to_i
+    end
+
+    def self.straight_alpha_composite_alpha_value(over_alpha, under_alpha)
+      aa = over_alpha.fdiv(255)
+      ab = under_alpha.fdiv(255)
+
+      # return alpha composited alpha component as integer in range 0..255
+      ((aa + ab * (1 - aa)) * 255).to_i
+    end
+
+    def self.straight_alpha_composite_color(over_color, under_color)
+      over_color_alpha = over_color.alpha
+      under_color_alpha = under_color.alpha
+
+      AsciiPngfy::ColorRGBA.new(
+        straight_alpha_composite_color_value(over_color.red, over_color_alpha, under_color.red, under_color_alpha),
+        straight_alpha_composite_color_value(over_color.green, over_color_alpha, under_color.green, under_color_alpha),
+        straight_alpha_composite_color_value(over_color.blue, over_color_alpha, under_color.blue, under_color_alpha),
+        straight_alpha_composite_alpha_value(over_color_alpha, under_color_alpha)
+      )
+    end
+
+    def self.possibly_blended_font_and_background_color(settings)
+      case settings.font_color.alpha
+      when 255
+        settings.font_color
+      else
+        straight_alpha_composite_color(settings.font_color, settings.background_color)
+      end
+    end
+
+    def self.design_character_pixel_color(settings, design_character)
+      if AsciiPngfy::Glyphs.font_layer_design_character?(design_character)
+        possibly_blended_font_and_background_color(settings)
+      elsif AsciiPngfy::Glyphs.background_layer_design_character?(design_character)
+        settings.background_color
+      end
+    end
+
+    def self.plot_font_regions_with_design(settings, png)
+      each_font_region_with_associated_character(settings) do |font_region, character|
+        # the only ASCII character that has an empty glyph desgn is the space
+        # so avoid unnecessary work for spaces
+        next if character == ' '
+
+        # mirror the font design for each font region into the png
+        font_region_character_design = AsciiPngfy::Glyphs::DESIGNS[character]
+
+        font_region.each_pixel_with_index do |font_pixel_x, font_pixel_y, font_pixel_index|
+          png_pixel_design_character = font_region_character_design[font_pixel_index]
+
+          png_pixel_plot_color = design_character_pixel_color(settings, png_pixel_design_character)
+          png_pixel_plot_color_as_integer = color_rgba_to_chunky_png_integer(png_pixel_plot_color)
+
+          png[font_pixel_x, font_pixel_y] = png_pixel_plot_color_as_integer
+        end
+      end
+    end
+
+    def self.plot_font_regions_without_design(settings, png)
+      final_font_color = possibly_blended_font_and_background_color(settings)
+      final_font_color_as_integer = color_rgba_to_chunky_png_integer(final_font_color)
+
+      each_font_region(settings) do |font_region|
+        # fill every font region entirely with, the potentially mixed, font and backround color
+        font_region.each_pixel do |font_region_x, font_region_y|
+          png[font_region_x, font_region_y] = final_font_color_as_integer
+        end
+      end
+    end
+
+    def self.plot_settings(settings, use_glyph_designs, png)
+      if use_glyph_designs
+        plot_font_regions_with_design(settings, png)
+      else
+        plot_font_regions_without_design(settings, png)
+      end
+    end
+  end
+end
+# rubocop: enable Metrics/ModuleLength