distorted 0.5.3 → 0.6.0

data/lib/distorted/modular_technology/triple_counter.rb

@@ -0,0 +1,45 @@
+TripleCounter = Struct.new(:major, :minor, :micro) do
+  attr_reader :major, :minor, :micro
+
+  def initialize(major = 0, minor = 0, micro = 0)
+    @major = major
+    @minor = minor
+    @micro = micro
+  end
+
+  def to_s
+    [major, minor, micro].join('.'.freeze)
+  end
+
+  def ==(otra)
+    major == otra.major && minor == otra.minor
+  end
+
+  def ===(otra)
+    all_operator(otra, :==)
+  end
+
+  def >=(otra)
+    all_operator(otra, :>=)
+  end
+
+  def <=(otra)
+    all_operator(otra, :<=)
+  end
+
+  def >(otra)
+    all_operator(otra, :>)
+  end
+
+  def <(otra)
+    all_operator(otra, :<)
+  end
+
+  def to_array
+    [major, minor, micro]
+  end
+
+  def all_operator(otra, operator)
+    to_array.zip(otra.to_array).all?{|us, otra| us.send(operator, otra)}
+  end
+end

data/lib/distorted/modular_technology/ttfunk.rb

@@ -0,0 +1,48 @@
+require 'ttfunk'
+
+module Cooltrainer; end
+module Cooltrainer::DistorteD; end
+module Cooltrainer::DistorteD::Technology; end
+module Cooltrainer::DistorteD::Technology::TTFunk
+
+  def to_ttfunk
+    # TODO: Check that src exists, because TTFunk won't and will just
+    # give us an unusable object instead.
+    @ttfunk_file ||= TTFunk::File.open(font_path)
+  end
+
+  # Returns a boolean for whether or not this font is monospaced.
+  # true == monospace
+  # false == proportional
+  def font_spacing
+    # Monospace fonts will (read: should) have the same width
+    # for every glyph, so we can tell a monospace font by
+    # checking if a deduplicated widths table has size == 1:
+    # irb(main)> font.horizontal_metrics.widths.count
+    # => 256
+    # irb(main)> font.horizontal_metrics.widths.uniq.compact.length
+    # => 1
+    to_ttfunk.horizontal_metrics.widths.uniq.compact.length == 1 ? :monospace : :proportional
+  end
+
+  # Returns the Family and Subfamily as one string suitable for libvips
+  def font_name
+    "#{to_ttfunk.name.font_family.first.encode('UTF-8')} #{to_ttfunk.name.font_subfamily.first.encode('UTF-8')}"
+  end
+
+  # Returns the Pango-Markup-encoded UTF-8 String version + revision of the font
+  def font_version
+    g_markup_escape_text(to_ttfunk.name&.version&.first&.encode('UTF-8').to_s)
+  end
+
+  # Returns the Pango-Markup-encoded UTF-8 String font file description
+  def font_description
+    g_markup_escape_text(to_ttfunk.name&.description&.first&.encode('UTF-8').to_s)
+  end
+
+  # Returns the Pango-Markup-encoded UTF-8 String copyright information of the font
+  def font_copyright
+    g_markup_escape_text(to_ttfunk.name&.copyright&.first&.encode('UTF-8').to_s)
+  end
+
+end

data/lib/distorted/modular_technology/vips.rb

@@ -0,0 +1,17 @@
+require 'set'
+
+require 'distorted/checking_you_out'
+
+require 'distorted/modular_technology/vips_load'
+require 'distorted/modular_technology/vips_save'
+
+
+module Cooltrainer; end
+module Cooltrainer::DistorteD; end
+module Cooltrainer::DistorteD::Technology; end
+module Cooltrainer::DistorteD::Technology::Vips
+
+  include Cooltrainer::DistorteD::Technology::VipsSave
+  include Cooltrainer::DistorteD::Technology::VipsLoad
+
+end

data/lib/distorted/modular_technology/vips_load.rb

@@ -0,0 +1,77 @@
+
+require 'set'
+
+require 'distorted/checking_you_out'
+require 'distorted/modular_technology/vips_save'
+
+
+module Cooltrainer; end
+module Cooltrainer::DistorteD; end
+module Cooltrainer::DistorteD::Technology; end
+module Cooltrainer::DistorteD::Technology::VipsLoad
+
+  # Returns a Set of MIME::Types based on libvips LipsForeignLoad capabilities.
+  # NOTE: libvips only declares support (via :get_suffixes) for the "saver" types,
+  #   but libvips can use additional external libraries for wider media-types support, e.g.:
+  #
+  # - SVG with librsvg2★ / libcairo. [*]
+  # - PDF with PDFium if available, otherwise with libpoppler-glib / libcairo.
+  # - OpenEXR/libIlmImf — ILM high dynamic range image format.
+  # - maybe more: https://github.com/libvips/libvips/blob/master/configure.ac
+  #
+  #   [FITS]: https://heasarc.gsfc.nasa.gov/docs/heasarc/fits.html
+  #
+  #   [RSVG2]: This is the normal SVG library for the GNOME/GLib world and is
+  #            probably fine for 95% of use-cases, but I'm pissed off at it because of:
+  #
+  #            - https://gitlab.gnome.org/GNOME/librsvg/-/issues/56
+  #            - https://gitlab.gnome.org/GNOME/librsvg/-/issues/100
+  #            - https://gitlab.gnome.org/GNOME/librsvg/-/issues/183
+  #            - https://gitlab.gnome.org/GNOME/librsvg/-/issues/494
+  #            - https://bugzilla.gnome.org/show_bug.cgi?id=666477
+  #            - https://phabricator.wikimedia.org/T35245
+  #
+  #            TLDR: SVG <tspan> elements' [:x, :y, :dy, :dx] attributes can be
+  #            a space-delimited list of position values for individual
+  #            characters in the <tspan>, but librsvg2 only supported reading
+  #            those attributes as a single one-shot numeric value.
+  #            Documents using this totally-common and totally-in-spec feature
+  #            rendered incorrectly with librsvg2. Effected <tspan> elements'
+  #            subsequent children would hug one edge of the rendered output.
+  #
+  #            And wouldn't you know it but the one (1) SVG on my website
+  #            at the time I built this feature (IIDX-Turntable-parts.svg) used
+  #            this feature for the double-digit parts diagram labels.
+  #            I ended up having to edit my input document to just squash the
+  #            offending <tspan>s down to a single child each.
+  #            I guess that's semantically more correct in my document since they are
+  #            numbers like Eleven and not two separate characters like '1 1'
+  #            but still ugh lol
+  #
+  #            This was finally fixed in 2019 as of librsvg2 version 2.45.91 :)
+  #            https://gitlab.gnome.org/GNOME/librsvg/-/issues/494#note_579774
+  #
+
+  # TODO: Figure out how to detect non-Magick non-Saver Loader support,
+  # by which I mean "everything not included in :get_suffixes".
+  # NOTE: The Magick-based '.bmp' loader is broken/missing in libvips <= 8.9.1:
+  # https://github.com/libvips/libvips/issues/1528
+  # irb> MIME::Types.type_for('.bmp')
+  # => [#<MIME::Type: image/bmp>, #<MIME::Type: image/x-bmp>, #<MIME::Type: image/x-ms-bmp>]
+  # irb> MIME::Types.type_for('.bmp').map(&:preferred_extension)
+  # => ["bmp", "bmp", "bmp"]
+  LOWER_WORLD = (VIPS_AVAILABLE_VER < TripleCounter.new(8, 9, 1)) ?
+    Cooltrainer::DistorteD::Technology::VipsSave::OUTER_LIMITS.keep_if { |t| t.preferred_extension != 'bmp'.freeze } :
+    Cooltrainer::DistorteD::Technology::VipsSave::OUTER_LIMITS
+
+  def to_vips_image
+    # TODO: Learn more about what VipsAccess means for our use case,
+    # if the default should be changed, and if it should be
+    # a user-controllable attr or not.
+    # https://libvips.github.io/libvips/API/current/VipsImage.html#VipsAccess
+    # https://libvips.github.io/libvips/API/current/How-it-opens-files.md.html
+    @vips_image ||= Vips::Image.new_from_file(path)
+  end
+
+
+end

data/lib/distorted/modular_technology/vips_save.rb

@@ -0,0 +1,172 @@
+
+# Requiring libvips 8.8 for HEIC/HEIF (moo) support, `justify` support in the
+# Vips::Image text operator, animated WebP support, and more:
+# https://libvips.github.io/libvips/2019/04/22/What's-new-in-8.8.html
+
+require 'distorted/modular_technology/triple_counter'
+VIPS_MINIMUM_VER = TripleCounter.new(8, 8, 0)
+
+# Tell the user to install the shared library if it's missing.
+begin
+  require 'vips'
+  VIPS_AVAILABLE_VER = TripleCounter.new(Vips::version(0), Vips::version(1), Vips::version(2))
+
+  unless VIPS_AVAILABLE_VER >= VIPS_MINIMUM_VER
+    raise LoadError.new(
+      "DistorteD needs libvips #{VIPS_MINIMUM_VER}, but the available version is '#{Vips::version_string}'"
+    )
+  end
+
+rescue LoadError => le
+  # Only match libvips.so load failure
+  raise unless le.message =~ /libvips.so/
+
+  # Multiple OS help
+  help = <<~INSTALL
+
+  Please install the VIPS (libvips) image processing library, version #{VIPS_MINIMUM_VER} or later.
+
+  FreeBSD:
+    pkg install graphics/vips
+
+  macOS:
+    brew install vips
+
+  Debian/Ubuntu/Mint:
+    apt install libvips libvips-dev
+  INSTALL
+
+  # Re-raise with install message
+  raise $!, "#{help}\n#{$!}", $!.backtrace
+end
+
+
+require 'set'
+
+require 'distorted/checking_you_out'
+
+
+module Cooltrainer; end
+module Cooltrainer::DistorteD; end
+module Cooltrainer::DistorteD::Technology; end
+module Cooltrainer::DistorteD::Technology::VipsSave
+
+  ATTRIBUTES = {
+    :crop => nil,
+    :Q => Set[:quality],
+  }
+  ATTRIBUTES_DEFAULT = {
+    :crop => :attention,
+  }
+  ATTRIBUTES_VALUES = {
+    # https://www.rubydoc.info/gems/ruby-vips/Vips/Interesting
+    :crop => {
+      :none => nil,
+      :centre => Set[:center],  # America, FUCK YEAH!
+      :entropy => nil,
+      :attention => nil,
+    },
+  }
+
+  # Returns a Set of MIME::Types based on libvips VipsForeignSave capabilities.
+  # https://libvips.github.io/libvips/API/current/VipsForeignSave.html
+  #
+  # There is one (only one) native libvips image format, with file extname `.vips`.
+  # As I write this—running libvips 8.8—the :get_suffixes function does not include
+  # its own '.vips' as a supported extension.
+  # There also (as of mid 2020) seems to be no official media-type assigned
+  # for VIPS format, so I am going to make one up in CHECKING::YOU::OUT's local-data.
+  # - Raw pixel data
+  #
+  # [RAW]: https://libvips.github.io/libvips/API/current/VipsForeignSave.html#vips-rawload
+  # https://libvips.github.io/libvips/API/current/VipsForeignSave.html#vips-csvload
+  #
+  # Most libvips installations, even very minimally-built ones,
+  # will almost certainly support a few very common formats:
+  # - JPEG with libjpeg.
+  # - PNG with libpng.
+  # - GIF with giflib.
+  # - WebP with libwebp.
+  # - TIFF with libtiff.
+  #
+  # Normal libvips installations probably also support many less-mainstream formats:
+  # - HEIF/HEIC with libheif.
+  # - ICC profiles with liblcms2.
+  # - Matlab with matio/libhdf5.
+  # - FITS★ with cfitsio.
+  # - Styled text with Pango/ft2.
+  # - Saving GIF/BMP with Magick.
+  #     NOTE that GIFs are *loaded* using giflib,
+  #     and that BMP loading is unsupported.
+  # - Various simple ASCII/binary-based formats with libgsf★
+  #   · Comma-separated values
+  #   · Netpbm★
+  #   · VIPS (non-Matlab) matrices★
+  #
+  # [NETPBM]: https://en.wikipedia.org/wiki/Netpbm#File_formats
+  # [LIBGSF]: https://developer.gnome.org/gsf/
+  # [MATRIX]: https://libvips.github.io/libvips/API/current/VipsForeignSave.html#vips-matrixload
+
+  # Vips allows us to query supported *SAVE* types by suffix.
+  # There's a simple relationship between filetype and extension since
+  # libvips uses the suffix to pick the Saver module.
+  #
+  # Loader modules, on the other hand, are picked by sniffing the
+  # first few bytes of the file, so a list of file extensions for
+  # supported loadable formats won't always be complete.
+  # For example, SVG and PDF are usually supported as loaders
+  # (via rsvg and PDFium/Poppler)
+  # https://github.com/libvips/ruby-vips/issues/186
+  #
+  # irb(main)> Vips.get_suffixes
+  # => [".csv", ".mat", ".v", ".vips", ".ppm", ".pgm", ".pbm", ".pfm",
+  #     ".hdr", ".dz", ".png", ".jpg", ".jpeg", ".jpe", ".webp", ".tif",
+  #     ".tiff", ".fits", ".fit", ".fts", ".gif", ".bmp"]
+  OUTER_LIMITS = Vips.get_suffixes.map{ |t|
+    # A single call to this will return a Set of MIME::Types for a String input
+    CHECKING::YOU::OUT(t)
+  }.reduce { |c,t|
+    # Flatten the Set-of-Sets-of-Types into a Set-of-Types
+    (c || Set[]).merge(t)
+  }.keep_if { |t|
+    # Filter out any of libvips' supported output Types that aren't
+    # actually images (e.g. CSV)
+    t.media_type == 'image'
+  }
+
+  # Define a to_<mediatype>_<subtype> method for each MIME::Type supported by libvips,
+  # e.g. a supported Type 'image/png' will define a method :to_image_png in any
+  # context where this module is included.
+  self::OUTER_LIMITS.each { |t|
+    define_method(t.distorted_method) { |*a, **k, &b|
+      vips_save(*a, **k, &b)
+    }
+  }
+
+  protected
+
+  # Generic Vips saver method, optionally handling resizing and cropping.
+  # NOTE: libvips chooses a saver (internally) based on the extname of the destination path.
+  def vips_save(dest, width: nil, **kw)
+    begin
+      if width.nil? or width == :full
+        return to_vips_image.write_to_file(dest)
+      elsif width.respond_to?(:to_i)
+        ver = to_vips_image.thumbnail_image(
+          width.to_i,
+          # Use `self` namespace for constants so subclasses can redefine
+          **{:crop => abstract(:crop)},
+        )
+        return ver.write_to_file(dest)
+      end
+    rescue Vips::Error => v
+      if v.message.include?('No known saver')
+        # TODO: Handle missing output formats. Replacements? Skip it? Die?
+        return nil
+      else
+        raise
+      end
+    end
+  end  # save
+
+end

data/lib/distorted/molecule/C18H27NO3.rb

@@ -0,0 +1,10 @@
+require 'distorted/injection_of_love'
+
+module Cooltrainer; end
+module Cooltrainer::DistorteD; end
+module Cooltrainer::DistorteD::Molecule; end
+module Cooltrainer::DistorteD::Molecule::C18H27NO3
+
+  BOOLEAN_ATTR_VALUES = Set[0, 1, false, true, '0'.freeze, '1'.freeze, 'false'.freeze, 'true'.freeze]
+
+end

data/lib/distorted/molecule/font.rb

@@ -0,0 +1,198 @@
+require 'set'
+
+# Font metadata extraction
+require 'ttfunk'
+
+require 'distorted/modular_technology/pango'
+require 'distorted/modular_technology/ttfunk'
+require 'distorted/modular_technology/vips_save'
+require 'distorted/checking_you_out'
+require 'distorted/injection_of_love'
+
+
+module Cooltrainer
+  module DistorteD
+    module Font
+
+
+      # TODO: Test OTF, OTB, and others.
+      # NOTE: Traditional bitmap fonts won't be supported due to Pango 1.44
+      # and later switching to Harfbuzz from Freetype:
+      # https://gitlab.gnome.org/GNOME/pango/-/issues/386
+      # https://blogs.gnome.org/mclasen/2019/05/25/pango-future-directions/
+      LOWER_WORLD = CHECKING::YOU::IN(/^font\/ttf/)
+      OUTER_LIMITS = CHECKING::YOU::IN(/^font\/ttf/)
+
+      ATTRIBUTES = Set[
+        :alt,
+      ]
+      ATTRIBUTES_VALUES = {
+      }
+      ATTRIBUTES_DEFAULT = {
+      }
+
+
+      # Maybe T0DO: Process output with TTFunk instead of only using it
+      # to generate images and metadata.
+      self::OUTER_LIMITS.each { |t|
+        define_method(t.distorted_method) { |*a, **k, &b|
+          copy_file(*a, **k, &b)
+        }
+      }
+
+      include Cooltrainer::DistorteD::Technology::TTFunk
+      include Cooltrainer::DistorteD::Technology::Pango
+      include Cooltrainer::DistorteD::Technology::VipsSave
+      include Cooltrainer::DistorteD::InjectionOfLove
+
+
+      # irb(main):089:0> chars.take(5)
+      # => [[1, 255], [2, 1], [3, 2], [4, 3], [5, 4]]
+      # irb(main):090:0> chars.values.take(5)
+      # => [255, 1, 2, 3, 4]
+      # irb(main):091:0> chars.values.map(&:chr).take(5)
+      # => ["\xFF", "\x01", "\x02", "\x03", "\x04"]
+      def to_pango
+        output = '' << cr << '<span>' << cr
+
+        output << "<span size='35387'> #{font_name}</span>" << cr << cr
+
+        output << "<span size='24576'> #{font_description}</span>" << cr
+        output << "<span size='24576'> #{font_copyright}</span>" << cr
+        output << "<span size='24576'> #{font_version}</span>" << cr << cr
+
+        # Print a preview String in using the loaded font. Or don't.
+        if abstract(:title)
+          output << cr << cr << "<span size='24576' foreground='grey'> #{g_markup_escape_text(abstract(:title))}</span>" << cr << cr << cr
+        end
+
+        #                        /!\ MANDATORY READING /!\
+        # https://developer.apple.com/fonts/TrueType-Reference-Manual/RM06/Chap6cmap.html
+        #
+        # "The 'cmap' table maps character codes to glyph indices.
+        # The choice of encoding for a particular font is dependent upon the conventions
+        # used by the intended platform. A font intended to run on multiple platforms
+        # with different encoding conventions will require multiple encoding tables.
+        # As a result, the 'cmap' table may contain multiple subtables,
+        # one for each supported encoding scheme."
+        #
+        # Cmap#unicode is a convenient shortcut to sorting the subtables
+        # and removing any unusable ones:
+        # https://github.com/prawnpdf/ttfunk/blob/master/lib/ttfunk/table/cmap.rb
+        #
+        # irb(main):174:0> font_meta.cmap.tables.count
+        # => 3
+        # irb(main):175:0> font_meta.cmap.unicode.count
+        # => 2
+        to_ttfunk.cmap.tables.each do |table|
+          next if !table.unicode?
+          # Each subtable's `code_map` is a Hash map of character codes (the Hash keys)
+          # to the glyph IDs from the original font (the Hash's values).
+          #
+          # Subtable::encode takes:
+          #  - a Hash mapping character codes to original font glyph IDs.
+          #  - the desired output encoding — Set[:mac_roman, :unicode, :unicode_ucs4]
+          #    https://github.com/prawnpdf/ttfunk/blob/master/lib/ttfunk/table/cmap/subtable.rb
+          # …and returns a Hash with keys:
+          #  - :charmap  — Hash mapping the characters in the input charmap
+          #                to a another hash containing both the `:old`
+          #                and `:new` glyph ids for each character code.
+          #  - :subtable — String encoded subtable for the given encoding.
+          encoded = TTFunk::Table::Cmap::Subtable::encode(table&.code_map, :unicode).dig(:charmap)
+
+          output << "<span size='49152'>"
+
+          i = 0
+          encoded.each_pair { |c, (old, new)|
+
+            begin
+              if glyph = to_ttfunk.glyph_outlines.for(c)
+                # Add a space on either side of the character so they aren't
+                # all smooshed up against each other and unreadable.
+                output << ' ' << g_markup_escape_char(c) << ' '
+                if i >= 15
+                  output << cr
+                  i = 0
+                else
+                  i = i + 1
+                end
+              else
+              end
+            rescue NoMethodError => nme
+              # TTFunk's `glyph_outlines.for()` will raise this if we call it
+              # for a codepoint that does not exist in the font, which we will
+              # not do because we are enumerating the codepoints in the font,
+              # but we should still handle the possibility.
+              # irb(main):060:0> font.glyph_outlines.for(555555)
+              #
+              # Traceback (most recent call last):
+              #   6: from /usr/bin/irb:23:in `<main>'
+              #   5: from /usr/bin/irb:23:in `load'
+              #   4: from /home/okeeblow/.gems/gems/irb-1.2.4/exe/irb:11:in `<top (required)>'
+              #   3: from (irb):60
+              #   2: from /home/okeeblow/.gems/gems/ttfunk-1.6.2.1/lib/ttfunk/table/glyf.rb:35:in `for'
+              #   1: from /home/okeeblow/.gems/gems/ttfunk-1.6.2.1/lib/ttfunk/table/loca.rb:35:in `size_of'
+              # NoMethodError (undefined method `-' for nil:NilClass)
+            end
+          }
+
+          output << '</span>' << cr
+        end
+
+        output << '</span>'
+        output
+      end
+
+      # Return the `src` as the font_path since we aren't using
+      # any of the built-in fonts.
+      def font_path
+        path
+      end
+
+      def to_vips_image
+        # https://libvips.github.io/libvips/API/current/libvips-create.html#vips-text
+        Vips::Image.text(
+          # This string must be well-escaped Pango Markup:
+          # https://developer.gnome.org/pango/stable/pango-Markup.html
+          # However the official function for escaping text is
+          # not implemented in Ruby GLib, so we have to do it ourselves.
+          to_pango,
+          **{
+            # String absolute path to TTF
+            :fontfile => font_path,
+            # It's not enough to just specify the TTF path;
+            # we must also specify a font family, subfamily, and size.
+            :font => "#{font_name}",
+            # Space between lines (in Points).
+            :spacing => to_ttfunk.line_gap,
+            # Requires libvips 8.8
+            :justify => false,
+            :dpi => 144,
+          },
+        )
+      end
+
+    end  # Font 
+  end  # DistorteD
+end  # Cooltrainer
+
+
+# Notes on file-format specifics and software-library-specifics
+#
+# # TTF (via TTFunk)
+# 
+# ## Cmap
+#
+# Each TTFunk::Table::Cmap::Format<whatever> class responds to `:supported?`
+# with its own internal boolean telling us if that Format is usable in TTFunk.
+# This has nothing to do with any font file itself, just the library code.
+# irb(main)> font.cmap.tables.map{|t| t.supported?}
+# => [true, true, true]
+#
+# Any subclass of TTFunk::Table::Cmap::Subtable responds to `:unicode?`
+# with a boolean calculated from the instance `@platform_id` and `@encoding_id`,
+# and those numeric IDs are assigned to the symbolic (e.g. `:macroman`) names in:
+# https://github.com/prawnpdf/ttfunk/blob/master/lib/ttfunk/table/cmap/subtable.rb
+# irb(main)> font.cmap.tables.map{|t| t.unicode?}
+# => [true, false, true]
+#