distorted 0.5.4 → 0.7.0

data/lib/distorted/media_molecule/font.rb

@@ -0,0 +1,195 @@
+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'
+
+
+module Cooltrainer; end
+module Cooltrainer::DistorteD; end
+module Cooltrainer::DistorteD::Molecule; end
+module Cooltrainer::DistorteD::Molecule::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/).to_hash
+  OUTER_LIMITS = CHECKING::YOU::IN(/^font\/ttf/).to_hash
+
+  ATTRIBUTES = Set[
+    :alt,
+  ]
+  ATTRIBUTES_VALUES = {
+  }
+  ATTRIBUTES_DEFAULT = {
+  }
+
+
+  # Maybe T0DO: Process output with TTFunk instead of only using it
+  # to generate images and metadata.
+  self::LOWER_WORLD.keys.each { |t|
+    define_method(t.distorted_file_method) { |dest_root, change|
+      copy_file(change.paths(dest_root).first)
+    }
+  }
+
+  include Cooltrainer::DistorteD::Technology::TTFunk
+  include Cooltrainer::DistorteD::Technology::Pango
+  include Cooltrainer::DistorteD::Technology::Vips::Save
+
+
+  # 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 
+
+
+# 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]
+# 

data/lib/distorted/media_molecule/image.rb

@@ -0,0 +1,33 @@
+
+require 'set'
+
+require 'distorted/checking_you_out'
+require 'distorted/modular_technology/vips'
+
+
+module Cooltrainer; end
+module Cooltrainer::DistorteD; end
+module Cooltrainer::DistorteD::Molecule; end
+module Cooltrainer::DistorteD::Molecule::Image
+
+
+  # Attributes for our <picture>/<img>.
+  # Automatically enabled as attrs for DD Liquid Tag.
+  # https://developer.mozilla.org/en-US/docs/Web/HTML/Element/picture#Attributes
+  # https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#Attributes
+  # https://developer.mozilla.org/en-US/docs/Web/Performance/Lazy_loading
+  ATTRIBUTES = Set[:alt, :caption, :href, :loading]
+
+  # Defaults for HTML Element attributes.
+  # Not every attr has to be listed here.
+  # Many need no default and just won't render.
+  ATTRIBUTES_DEFAULT = {
+    :loading => :eager,
+  }
+  ATTRIBUTES_VALUES = {
+    :loading => Set[:eager, :lazy],
+  }
+
+  include Cooltrainer::DistorteD::Technology::Vips
+
+end  # Image

data/lib/distorted/media_molecule/pdf.rb

@@ -0,0 +1,44 @@
+require 'set'
+
+require 'hexapdf'
+
+require 'distorted/checking_you_out'
+
+
+module Cooltrainer; end
+module Cooltrainer::DistorteD; end
+module Cooltrainer::DistorteD::Molecule; end
+module Cooltrainer::DistorteD::Molecule::PDF
+
+
+  # https://hexapdf.gettalong.org/documentation/reference/api/HexaPDF/Document/index.html#method-c-new
+  # https://hexapdf.gettalong.org/documentation/reference/api/HexaPDF/index.html#DefaultDocumentConfiguration
+  # https://hexapdf.gettalong.org/documentation/reference/api/HexaPDF/Task/Optimize.html
+  PDF_TYPE = CHECKING::YOU::OUT['application/pdf']
+  LOWER_WORLD = Hash[
+    PDF_TYPE => nil,
+  ]
+  OUTER_LIMITS = Hash[
+    PDF_TYPE => nil,
+  ]
+
+  # TODO: Use MuPDF instead of libvips magick-based PDF loader.
+
+  def self.optimize(src, dest)
+    HexaPDF::Document.open(src) do |doc|
+      doc.task(
+        :optimize,
+        compact: true,
+        object_streams: :generate,
+        xref_streams: :generate,
+        compress_pages: false,
+      )
+      doc.write(dest)
+    end
+  end
+
+  define_method(PDF_TYPE.distorted_file_method) { |dest_root, change|
+    copy_file(change.paths(dest_root).first)
+  }
+
+end  # PDF

data/lib/distorted/media_molecule/svg.rb

@@ -0,0 +1,45 @@
+require 'set'
+
+require 'svg_optimizer'  # https://github.com/fnando/svg_optimizer
+
+require 'distorted/checking_you_out'
+require 'distorted/modular_technology/vips/save'
+
+
+module Cooltrainer; end
+module Cooltrainer::DistorteD; end
+module Cooltrainer::DistorteD::Molecule; end
+module Cooltrainer::DistorteD::Molecule::SVG
+
+  include Cooltrainer::DistorteD::Technology::Vips::Save
+
+  LOWER_WORLD = Hash[
+    CHECKING::YOU::OUT['image/svg+xml'] => Cooltrainer::DistorteD::Technology::Vips::vips_get_options(
+      Cooltrainer::DistorteD::Technology::Vips::vips_foreign_find_load_suffix(".#{CHECKING::YOU::OUT['image/svg+xml'].preferred_extension}")
+    ).merge(Hash[
+      :optimize => Cooltrainer::Compound.new(:optimize, valid: Cooltrainer::BOOLEAN_VALUES, default: false, blurb: 'SvgOptimizer'),
+    ])
+  ]
+
+  # WISHLIST: Support VML for old IE compatibility.
+  #  Example: RaphaëlJS — https://en.wikipedia.org/wiki/Rapha%C3%ABl_(JavaScript_library)
+  OUTER_LIMITS = Hash[
+    CHECKING::YOU::OUT['image/svg+xml'] => nil,
+  ]
+
+  def to_vips_image
+    # NOTE: libvips 8.9 added the `unlimited` argument to svgload.
+    # Loading SVGs >= 10MiB in size will fail on older libvips.
+    # https://github.com/libvips/libvips/commit/55e49831b801e05ddd974b1e2102fda7956c53f5
+    @vips_image ||= Vips::Image.new_from_file(path)
+  end
+
+  define_method(CHECKING::YOU::OUT['image/svg+xml'].distorted_file_method) { |dest_root, change|
+    if change.optimize
+      SvgOptimizer.optimize_file(path, change.paths(dest_root).first, SvgOptimizer::DEFAULT_PLUGINS)
+    else
+      copy_file(change.paths(dest_root).first)
+    end
+  }
+
+end

data/lib/distorted/media_molecule/text.rb

@@ -0,0 +1,203 @@
+require 'set'
+
+require 'charlock_holmes'  # Text file charset detection
+
+require 'distorted/monkey_business/encoding'
+require 'distorted/monkey_business/string'  # String#map
+require 'distorted/modular_technology/pango'
+require 'distorted/modular_technology/ttfunk'
+require 'distorted/modular_technology/vips/save'
+
+require 'distorted/checking_you_out'
+
+
+module Cooltrainer; end
+module Cooltrainer::DistorteD; end
+module Cooltrainer::DistorteD::Molecule; end
+module Cooltrainer::DistorteD::Molecule::Text
+
+  #TODO: Generate separate images per-size to stop text being blurry from resizing.
+
+  include Cooltrainer::DistorteD::Technology::TTFunk
+  include Cooltrainer::DistorteD::Technology::Pango
+  include Cooltrainer::DistorteD::Technology::Vips::Save
+
+  # Track supported fonts by codepage.
+  # Avoid renaming these from the original archives / websites.
+  # Try not to go nuts here bloating the size of our Gem for a
+  # very niche feature, but I want to ensure good coverage too.
+  #
+  # Treat codepage 8859 documents as codepage 1252 to avoid breaking smart-
+  # quotes and other printable chars in 1252 that are control chars in 8859.
+  # https://encoding.spec.whatwg.org/#names-and-labels
+  #
+  # Numeric key for UTF-8 is codepage 65001 like Win32:
+  # https://docs.microsoft.com/en-us/windows/win32/intl/code-page-identifiers
+  FONT_FILENAME = {
+    :anonpro => 'Anonymous Pro.ttf'.freeze,
+    :anonpro_b => 'Anonymous Pro B.ttf'.freeze,
+    :anonpro_bi => 'Anonymous Pro BI.ttf'.freeze,
+    :anonpro_i => 'Anonymous Pro I.ttf'.freeze,
+    :lessperfectdosvga => 'LessPerfectDOSVGA.ttf'.freeze,
+    :moreperfectdisvga => 'MorePerfectDOSVGA.ttf'.freeze,
+    :perfectdosvgawin => 'Perfect DOS VGA 437 Win.ttf'.freeze,
+    :mona => 'mona.ttf'.freeze,
+    :perfectdosvga => 'Perfect DOS VGA 437.ttf'.freeze,
+    :profont => 'ProFontWindows.ttf'.freeze,
+    :profont_b => 'ProFontWindows-Bold.ttf'.freeze,
+  }
+  # Certain fonts are more suitable for certain codepages,
+  # so track each codepage's available fonts…
+  CODEPAGE_FONT = {
+    65001 => [
+      :anonpro,
+      :anonpro_b,
+      :anonpro_bi,
+      :anonpro_i,
+    ],
+    1252 => [
+      :lessperfectdosvga,
+      :moreperfectdosvga,
+      :perfectdosvgawin,
+    ],
+    932 => [
+      :mona,
+    ],
+    850 => [
+      :profont,
+      :profont_b,
+    ],
+    437 => [
+      :perfectdosvga,
+    ],
+  }
+  # …as well as the inverse, the numeric codepage for each font:
+  FONT_CODEPAGE = self::CODEPAGE_FONT.reduce(Hash.new([])) { |memo, (key, values)|
+    values.each { |value| memo[value] = key }
+    memo
+  }
+
+
+  LOWER_WORLD = CHECKING::YOU::IN(/^text\/(plain|x-nfo)/).to_hash.transform_values { |v| Hash[
+    :encoding => Cooltrainer::Compound.new(:encoding, blurb: 'Character encoding used in this document.', default: 'UTF-8'.freeze),
+  ]}
+  OUTER_LIMITS = CHECKING::YOU::IN(/^text\/(plain|x-nfo)/).to_hash.merge(
+    Cooltrainer::DistorteD::Technology::Vips::Save::OUTER_LIMITS.dup.transform_values{ |v| Hash[
+      :spacing => Cooltrainer::Compound.new(:spacing, blurb: 'Document-wide character spacing style.', valid: Set[:monospace, :proportional]),
+      :dpi => Cooltrainer::Compound.new(:dpi, blurb: 'Dots per inch for text rendering.', valid: Integer, default: 144),
+      :font => Cooltrainer::Compound.new(:font, blurb: 'Font to use for text rendering.', valid: self::FONT_FILENAME.keys.to_set),
+    ]}
+  )
+
+  self::LOWER_WORLD.keys.each { |t|
+    define_method(t.distorted_file_method) { |dest_root, change|
+      copy_file(change.paths(dest_root).first)
+    }
+  }
+
+
+  # Return a Pango Markup escaped version of the document.
+  def to_pango
+    # https://developer.gnome.org/glib/stable/glib-Simple-XML-Subset-Parser.html#g-markup-escape-text
+    escaped = text_file_utf8_content.map{ |c|
+      g_markup_escape_char(c)
+    }
+    if font_spacing == :monospace
+      "<tt>" << escaped << "</tt>"
+    else
+      escaped
+    end
+  end
+
+  protected
+
+  def text_file_content
+    # VIPS makes us provide the text content as a single variable,
+    # so we may as well just one-shot File.read() it into memory.
+    # https://kunststube.net/encoding/
+    @text_file_content ||= File.read(path)
+  end
+
+  def text_file_utf8_content
+    CharlockHolmes::Converter.convert(text_file_content, text_file_encoding.to_s, 'UTF-8'.freeze)
+  end
+
+  def text_file_encoding
+    # It's not easy or even possible in some cases to tell the "true" codepage
+    # we should use for any given text document, but using character detection
+    # is worth a shot if the user gave us nothing.
+    #
+    # TODO: Figure out if/how we can get IBM437 files to not be detected as ISO-8859-1
+    @text_file_encoding ||= Encoding::find(
+      abstract(:encoding).to_s ||
+      CharlockHolmes::EncodingDetector.detect(text_file_content)[:encoding] ||
+      'UTF-8'.freeze
+    )
+  end
+
+  def vips_font
+    # Set the shorthand Symbol key for our chosen font.
+    return abstract(:font)&.to_sym || CODEPAGE_FONT[text_file_encoding.code_page].first
+  end
+
+  def to_vips_image
+    # Load font metadata directly from the file so we don't have to
+    # duplicate it here to feed to Vips/Pango.
+    #
+    # irb(main)> font_meta.name.font_name
+    # => ["Perfect DOS VGA 437", "\x00P\x00e\x00r\x00f\x00e\x00c\x00t\x00 \x00D\x00O\x00S\x00 \x00V\x00G\x00A\x00 \x004\x003\x007"]
+    # irb(main)> font_meta.name.font_family
+    # => ["Perfect DOS VGA 437", "\x00P\x00e\x00r\x00f\x00e\x00c\x00t\x00 \x00D\x00O\x00S\x00 \x00V\x00G\x00A\x00 \x004\x003\x007"]
+    # irb(main)> font_meta.name.font_subfamily
+    # => ["Regular", "\x00R\x00e\x00g\x00u\x00l\x00a\x00r"]
+    # irb(main)> font_meta.name.postscript_name
+    # => "PerfectDOSVGA437"
+    # irb(main)> font_meta.line_gap
+    # => 0
+
+    # 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} 16",
+        # Space between lines (in Points).
+        :spacing => to_ttfunk.line_gap,
+        :justify => true,  # Requires libvips 8.8
+        :dpi => abstract(:dpi)&.to_i,
+      },
+    )
+  end
+
+  # Return the String absolute path to the TTF file
+  def font_path
+    File.join(
+      File.dirname(__FILE__),  # molecule
+      '..'.freeze,  # distorted
+      '..'.freeze,  # lib
+      '..'.freeze,  # DistorteD-Floor
+      'font'.freeze,
+      font_codepage.to_s,
+      font_filename,
+    )
+  end
+
+  # Returns the numeric representation of the codepage
+  # covered by our font.
+  def font_codepage
+    FONT_CODEPAGE.dig(vips_font).to_s
+  end
+
+  # Returns the basename (with file extension) of our font.
+  def font_filename
+    FONT_FILENAME.dig(vips_font)
+  end
+
+end  # Text