distorted-floor 0.7.0

data/lib/distorted-floor/modular_technology/vips/ffi.rb

@@ -0,0 +1,66 @@
+# 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('xross-the-xoul/version') unless defined?(::XROSS::THE::Version::TripleCounter)
+VIPS_MINIMUM_VER = ::XROSS::THE::Version::TripleCounter.new(8, 8, 0)
+
+# Tell the user to install the shared library if it's missing or too old.
+begin
+  require 'vips'
+  VIPS_AVAILABLE_VER = ::XROSS::THE::Version::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
+
+# FFI Struct layout to read a VipsObject class summary.
+# Based on https://github.com/libvips/ruby-vips/issues/186#issuecomment-433691412
+module Vips
+  attach_function :vips_class_find, [:string, :string], :pointer
+  attach_function :vips_object_summary_class, [:pointer, :pointer], :void
+
+  class BufStruct < ::FFI::Struct
+    layout :base, :pointer,
+           :mx, :int,
+           :i, :int,
+           :full, :bool,
+           :lasti, :int,
+           :dynamic, :bool
+  end
+
+end
+
+module GObject
+  # Fundamental types not already defined in ruby-vips' `lib/vips.rb`
+  GBOXED_TYPE = g_type_from_name('GBoxed')
+
+  # Attach to functions that aren't already attached in `lib/vips/object.rb`,
+  # `lib/vips/operation.rb`, `lib/vips/gvalue.rb`, `lib/vips/gobject.rb`,
+  # or some other related file.
+  attach_function :g_param_spec_get_default_value, [:pointer], GValue
+end

data/lib/distorted-floor/modular_technology/vips/load.rb

@@ -0,0 +1,174 @@
+
+require 'set'
+
+require 'distorted-floor/checking_you_out'
+using ::DistorteD::CHECKING::YOU::OUT
+require 'distorted-floor/modular_technology/vips/operation'
+require 'distorted-floor/modular_technology/vips/save'
+
+
+module Cooltrainer; end
+module Cooltrainer::DistorteD; end
+module Cooltrainer::DistorteD::Technology; end
+module Cooltrainer::DistorteD::Technology::Vips::Load
+
+  # Returns a `::Set` of `::CHECKING::YOU::OUT` based on libvips `VipsForeignLoad` 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
+  #
+  #   [MAGICK]: The Magick-based '.bmp' loader is broken/missing in libvips <= 8.9.1,
+  #            but our automatic Loader detection will handle that. Just FYI :)
+  #
+
+  # Vips::vips_foreign_find_save is based on filename suffix (extension),
+  # but :vips_foreign_find_load seems to be based on file magic.
+  # That is, we can't `vips_foreign_find_load` for a made-up filename
+  # or plain suffix like we can to to build 'vips/save'::OUTER_LIMITS.
+  # This caught me off guard but doesn't *entirely* not-make-sense,
+  # considering Vips::Image::new_from_filename calls :vips_foreign_find_load
+  # and obviously expects a file to be present.
+  #
+  ## Example — works with real file and fails with only suffix:
+  # irb> Vips::vips_foreign_find_load '/home/okeeblow/cover.jpg'
+  # => "VipsForeignLoadJpegFile"
+  # irb> Vips::vips_foreign_find_load 'cover.jpg'
+  # => nil
+  #
+  ## Syscalls of successful real-file :vips_foreign_find_load call
+  # showing how it works:
+  # [okeeblow@emi#okeeblow] strace ruby -e "require 'vips'; Vips::vips_foreign_find_load '/home/okeeblow/cover.jpg'" 2>&1|grep cover.jpg
+  # access("/home/okeeblow/cover.jpg", R_OK) = 0
+  # openat(AT_FDCWD, "/home/okeeblow/cover.jpg", O_RDONLY) = 5
+  # openat(AT_FDCWD, "/home/okeeblow/cover.jpg", O_RDONLY) = 5
+  # openat(AT_FDCWD, "/home/okeeblow/cover.jpg", O_RDONLY) = 5
+  # openat(AT_FDCWD, "/home/okeeblow/cover.jpg", O_RDONLY) = 5
+  # openat(AT_FDCWD, "/home/okeeblow/cover.jpg", O_RDONLY|O_CLOEXEC) = 5
+  # openat(AT_FDCWD, "/home/okeeblow/cover.jpg", O_RDONLY|O_CLOEXEC) = 5
+  # lstat("/home/okeeblow/cover.jpg", {st_mode=S_IFREG|0740, st_size=6242228, ...}) = 0
+  # openat(AT_FDCWD, "/home/okeeblow/cover.jpg", O_RDONLY|O_CLOEXEC) = 5
+  # stat("/home/okeeblow/cover.jpg", {st_mode=S_IFREG|0740, st_size=6242228, ...}) = 0
+  # stat("/home/okeeblow/cover.jpg-journal", 0x7fffa70f4df0) = -1 ENOENT (No such file or directory)
+  # stat("/home/okeeblow/cover.jpg-wal", 0x7fffa70f4df0) = -1 ENOENT (No such file or directory)
+  # stat("/home/okeeblow/cover.jpg", {st_mode=S_IFREG|0740, st_size=6242228, ...}) = 0
+  # openat(AT_FDCWD, "/home/okeeblow/cover.jpg", O_RDONLY) = 5
+  #
+  ## …and of a fake suffix-only filename to show how it doesn't:
+  # [okeeblow@emi#okeeblow] strace ruby -e "require 'vips'; Vips::vips_foreign_find_load 'fartbutt.jpg'" 2>&1|grep '.jpg'
+  # read(5, ".write_to_target target, \".jpg[Q"..., 8192) = 8192
+  # access("fartbutt.jpg", R_OK)            = -1 ENOENT (No such file or directory)
+  #
+  ## Versus the corresponding Vips::vips_foreign_find_save which is *only* based
+  # on filename suffix and does not try to look at a file at all,
+  # perhaps (read: obviously) because that file wouldn't exist yet to test until we save it :)
+  # [okeeblow@emi#okeeblow] strace ruby -e "require 'vips'; p Vips::vips_foreign_find_save 'fartbutt.jpg'" 2>&1|grep -E 'Save|.jpg'
+  # read(5, ".write_to_target target, \".jpg[Q"..., 8192) = 8192
+  # write(1, "\"VipsForeignSaveJpegFile\"\n", 26"VipsForeignSaveJpegFile"
+  #
+  # For this reason I'm going to write my own shim Loader-finder and use it instead.
+  LOWER_WORLD = Cooltrainer::DistorteD::Technology::Vips::VipsType::loader_types.keep_if { |type, operations|
+    # Skip text types for image data until I have a way for multiple
+    # type-supporting Molecules to vote on a src file.
+    # TODO: Support loading image CSV
+    # TODO: Make this more robust/automatic.
+    Array[
+      type.phylum != :application,  # e.g. application/pdf
+      type.phylum != :text,  # e.g. text/csv
+    ].all? && Array[
+      type.genus.to_s.include?(-'zip'),
+      # Skip declaring SVG here since I want to handle it in a Vector-only Molecule
+      # and will re-declare this there. Prolly need to think up a better way to do this.
+      type.genus.to_s.include?(-'svg'),
+    ].none?
+  }.transform_values { |v| v.map(&:options).reduce(&:merge) }
+
+
+  self::LOWER_WORLD.each_key { |t|
+    define_method(t.distorted_open_method) { |src_path = path, change|
+      # Find a VipsType Struct for the saver operation
+      vips_operation = Cooltrainer::DistorteD::Technology::Vips::VipsType::loader_for(t).first
+
+      # Prepare a Hash of options appropriate for this operation.
+      # We explicitly declare all supported VipsArguments, using the FFI-detected
+      # default values for keys with no user-given value.
+      options = change.to_hash.slice(
+        # Get an Array[Symbol] of non-aliased option keys.
+        # Loading any aliases' values happens when the Change/Atoms are constructed.
+        *vips_operation.options.keep_if { |aka, compound| aka == compound.element }.keys
+      ).reject { |k,v| v.nil? }.transform_keys { |k|
+        # The `ruby-vips` binding expects hyphenated argument names to be converted to underscores:
+        # https://github.com/libvips/ruby-vips/blob/4f696e30796adcc99cbc70ff7fd778439f0cbac7/lib/vips/operation.rb#L78-L80
+        k.to_s.gsub('-', '_').to_sym
+      }
+
+      # Do the thing.
+      Vips::Operation.call(
+        # `:vips_call` expects the operation_name to be a String:
+        # https://libvips.github.io/libvips/API/current/VipsOperation.html#vips-call
+        vips_operation.name.to_s,
+        # Loaders only take the source path as a required argument.
+        [src_path],
+        # Operation-appropriate options Hash
+        options,
+        # `:options_string`, unused since we have everything in our Hash.
+        ''.freeze,
+      )
+    }
+  }
+
+
+  # Returns a Vips::Image from a file source.
+  # TODO: Get rid of this method! This is an old entrypoint.
+  #       Consume lower Types as a Change once we support Change chaining, then execute a chain.
+  def to_vips_image(change = nil)
+    @vips_image ||= begin
+      lower_config = the_setting_sun(:lower_world, *(type_mars.first&.settings_paths)) || Hash.new
+      atoms = Hash.new
+      lower_world[type_mars.first].values.reduce(&:concat).each_pair { |aka, compound|
+        next if aka != compound.element  # Skip alias Compounds since they will all be handled at once.
+        atoms.store(compound.element, Cooltrainer::Atom.new(compound.isotopes.reduce(nil) { |value, isotope|
+          value || lower_config.fetch(isotope, nil) || context_arguments&.fetch(isotope, nil)
+        }, compound.default))
+      }
+      self.send(type_mars.first.distorted_open_method, **atoms.transform_values(&:get))
+    end
+  end
+
+
+end

data/lib/distorted-floor/modular_technology/vips/operatio$.rb

@@ -0,0 +1,268 @@
+require 'set'
+require 'distorted-floor/modular_technology/vips/ffi'
+
+require 'distorted-floor/checking_you_out'
+require 'distorted-floor/element_of_media'
+
+
+module Cooltrainer; end
+module Cooltrainer::DistorteD; end
+module Cooltrainer::DistorteD::Technology; end
+module Cooltrainer::DistorteD::Technology::Vips
+
+
+  # 🄵🄸🄽🄳 🅃🄷🄴 🄲🄾🄼🄿🅄🅃🄴🅁 🅁🄾🄾🄼
+  # 🄵🄸🄽🄳 🅃🄷🄴 🄲🄾🄼🄿🅄🅃🄴🅁 🅁🄾🄾🄼
+  # 🄵🄸🄽🄳 🅃🄷🄴 🄲🄾🄼🄿🅄🅃🄴🅁 🅁🄾🄾🄼
+  Vips::vips_vector_set_enabled(1)
+
+
+  # All of the actual Loader/Saver classes we need to interact with
+  # will be tree children of one of these top-level class categories:
+  TOP_LEVEL_FOREIGN = :VipsForeign
+  TOP_LEVEL_LOADER  = :VipsForeignLoad
+  TOP_LEVEL_SAVER   = :VipsForeignSave
+
+
+  # Aliases we want to support for consistency and accessibility.
+  VIPS_ALIASES = {
+    :Q => Set[:Q, :quality],
+    :colours => Set[:colours, :colors],
+    :centre => Set[:centre, :center],  # America; FUCK YEAH!
+  }
+
+
+  # GEnum valid values are detectable, but I don't know how to do the same
+  # for the numeric parameters. Specify them here manually for now.
+  VIPS_VALID = {
+    :"page-height" => (0..Vips::MAX_COORD),
+    :"quant-table" => (0..8),
+    :Q => (0..100),
+    :colours => (2..256),
+    :dither => (0.0..1.0),
+    :compression => (0..9),
+    :"alpha-q" => (0..100),
+    :"reduction-effort" => (0..6),
+    :kmin => (0..0x7FFFFFFF),  # https://en.wikipedia.org/wiki/2,147,483,647
+    :kmax => (0..0x7FFFFFFF),
+    :"tile-width" => (0..0x8000),  # 32768
+    :"tile-height" => (0..0x8000),
+    :xres => (0.001..1e+06),
+    :yres => (0.001..1e+06),
+  }
+
+
+  # Encapsulate any VipsObject descendant based on GType ID or name
+  VipsType = Struct.new(:id) do
+    def initialize(id_or_name)
+      super(id_or_name.is_a?(Integer) ? id_or_name : GObject::g_type_from_name(id_or_name.to_s))
+    end
+    def name; GObject::g_type_name(self.id); end
+    def to_s; self.name.to_s; end
+    def to_sym; self.name.to_sym; end
+    def nickname; Vips::nickname_find(self.id); end
+    def inspect; "#<#{self.name}>"; end
+
+    # Returns an Array[String] of VipsForeign suffixes.
+    #
+    # Suffixes are defined in a NULL-terminated C Array in each VIPS class:
+    # https://github.com/libvips/libvips/search?p=3&q=suffs%5B%5D
+    # It's kinda silly but the best way to discover these is parse them
+    # out of the single-line String descriptions as seen in `vips -l`.
+    def suffixes
+      @suffixes ||= begin
+        # vips_class_find returns an FFI::Pointer, and we can use our own class name as the first param:
+        # irb> Vips::vips_class_find('VipsForeignSaveJpegFile', 'jpegsave')
+        # => #<FFI::Pointer address=0x00005592a24bac40>
+        vips_class_pointer = Vips::vips_class_find(TOP_LEVEL_FOREIGN.to_s, nickname)
+        return Array.new if vips_class_pointer.null?
+        # 2K buffer should always be big enough to read single-line Strings like these:
+        # VipsForeignLoadJpegFile (jpegload), load jpeg from file (.jpg, .jpeg, .jpe), priority=50, is_a, get_flags, header, load
+        buf_struct = Vips::BufStruct.new
+        buf_struct_string = ::FFI::MemoryPointer.new(:char, 2048)
+        buf_struct[:base] = buf_struct_string
+        buf_struct[:mx] = 2048
+        Vips::vips_object_summary_class(vips_class_pointer, buf_struct.pointer)
+        class_summary = buf_struct_string.read_string
+
+        # Parse an Array[String] of file extensions out of a class summary.
+        class_summary.scan(/\.\w+\.?\w+/)
+      end
+    end  # suffixes
+
+    # Returns a Hash[aka] => Compound based on this VipsType's VipsArguments.
+    def options
+      @options ||= Hash.new.tap { |options|
+        # `:vips_argument_map` itself will return void/nil, so we need to give it a function that modifies an existing Hash.
+        Vips::vips_argument_map(
+          # `:vips_operation_new` takes a String argument of the nickname, not the fullname:
+          # https://libvips.github.io/libvips/API/current/VipsOperation.html#vips-operation-new
+          Vips::vips_operation_new(self.nickname),
+          # `:vips_argument_map`'s second argument is a VipsArgumentMapFn to call for each VipsArgument:
+          # https://libvips.github.io/libvips/API/current/VipsObject.html#VipsArgumentMapFn
+          Proc.new { |_vips_object, param_spec, argument_class, _argument_instance|
+            flags = argument_class[:flags]
+            if (flags & Vips::ARGUMENT_INPUT) != 0  # We only want "input" arguments
+              # …and we also only want optional non-deprecated arguments.
+              if (flags & Vips::ARGUMENT_REQUIRED) == 0 && (flags & Vips::ARGUMENT_DEPRECATED) == 0
+                # ParameterSpec name will be a String e.g. 'Q' or 'interlace' or 'page-height'
+                element = param_spec[:name].to_sym
+
+                # `magicksave` takes an argument `format` to choose one of its many supported types,
+                # but that selection in DistorteD-land is via `::CHECKING::YOU::OUT()`, so this option should be dropped.
+                # https://github.com/libvips/libvips/blob/4de9b56725862edf872ae503a3dfb4cf05da9e77/libvips/foreign/magicksave.c#L455~L460
+                next if element == :format
+
+                Cooltrainer::Compound.new(
+                  # Support aliasing options like 'Q' into 'quality' for consistency
+                  # and 'colours' into 'colors' for accessibility.
+                  VIPS_ALIASES.dig(element) || Set[element],
+                  # Some libvips drivers seem to have mixed-leading-case options,
+                  # like ppmsave and webp save for example:
+                  # https://github.com/libvips/libvips/blob/4de9b56725862edf872ae503a3dfb4cf05da9e77/libvips/foreign/ppmsave.c#L396~L415
+                  # https://github.com/libvips/libvips/blob/4de9b56725862edf872ae503a3dfb4cf05da9e77/libvips/foreign/webpsave.c#L152
+                  blurb: GObject::g_param_spec_get_blurb(param_spec).tap { |blurb| blurb[0] = blurb[0].capitalize },
+                  default: self.class.get_argument_default(param_spec),
+                  valid: self.class.get_argument_valid_values(param_spec),
+                ).tap { |compound|
+                  # Add the Compound for every alias
+                  compound.isotopes.each{ |isotope| options.store(isotope, compound) }
+                }
+              end
+            end
+
+            # This isn't really a 'Saver' Option — rather an argument to a separate
+            # :smartcrop or :thumbnail VIPS method we can call, but I want to offer
+            # this option on every Type and use it to control the method we call
+            # to write the image.
+            # TODO: Handle VipsThumbnailImage's (and other Operations') full `:options` and remove this one-off.
+            #       This is here as a temporary shim for feature parity during refactoring.
+            # TODO: VipsType#parent method so we can check upward for :VipsForeign heritage.
+            if self.name.include?('Foreign'.freeze) and self.name.include?('Save'.freeze)
+              options.store(:crop, self.class.new(:VipsThumbnailImage).options.fetch(:crop, nil))
+            end
+          },
+          nil,  # `:a` "Client data"
+          nil,  # `:b` "Client data"
+        )
+      }
+    end
+
+    # Returns a Set[CHECKING::YOU::OUT] based on our suffixes.
+    def types
+      @types ||= begin
+        # We will likely get duplicate suffixes for a single `::CHECKING::YOU::OUT`, but we may also get suffixes for multiple Types:
+        # irb> Cooltrainer::DistorteD::Technology::Vips::FFI::VipsType.new('VipsForeignSaveJpegFile').suffixes
+        # => [".jpg", ".jpeg", ".jpe"]
+        # irb> Cooltrainer::DistorteD::Technology::Vips::FFI::VipsType.new('VipsForeignSaveMagickFile').suffixes
+        # => [".gif", ".bmp"]
+        # TODO: CYO shouldn't make us prepend '*'.
+        # TODO: Warn when we don't have a CYO match for a VIPS suffix (taken care of by `#compact` for now).
+        # TODO: Fix mis-detection of Radiance HDR and fix handling of `Set`s here (currently `#flatten`ed)
+        self.suffixes&.map { _1.prepend(-?*) }.map(&::CHECKING::YOU::OUT::method(:from_postfix)).compact.to_set.flatten
+      end
+    end  # types
+
+    # Returns an Array[VipsType] of our direct children.
+    def children
+      # https://libvips.github.io/libvips/API/current/VipsObject.html#vips-type-map
+      # "Map over a type's children. Stop when fn returns non-nil and return that value."
+      child_ids = Array.new
+      # vips_type_map will return an FFI::Pointer, so we can't return it directly.
+      Vips::vips_type_map(self.id, child_ids.method(:append).to_proc, nil)
+      # Calling :append in :vips_type_map will append a g_type as well as a FFI::Pointer to 0x0,
+      # so filter the pointers out (Interger g_types only), then turn it each child
+      # into another Hash of it to its children.
+      child_ids.select { |c| c.is_a?(Integer) }.map(&self.class.method(:new))
+    end
+
+    # Returns a Hash[self] => Array[VipsType/Hash] of our children and all of their childrens' children.
+    # Array members will be another Hash[child] => Array[grandchildren] if our children
+    # have any children, or just the child VipsType if it doesn't.
+    def family_tree
+      # Return only ourselves as a value instead of another empty Hash if we have no children.
+      children.empty? ? self : Hash[self => children.map(&:family_tree)]
+    end
+
+    # Returns an Array[VipsType] of all of our children and all of their children and
+    def family_reunion
+      self.children.each_with_object(Array[self]) { |child, family|
+        family.push(*child.family_reunion)
+      }
+    end
+
+    # Returns an `Array[VipsType]` of loaders/savers given a filename, suffix, or `::CHECKING::YOU::OUT`.
+    def self.loader_for(given); self.foreign_for(TOP_LEVEL_LOADER, given); end
+    def self.saver_for(given);  self.foreign_for(TOP_LEVEL_SAVER,  given); end
+
+    # Returns a Hash[CHECKING::YOU::OUT] => Set[VipsType] of loaders/savers.
+    def self.loader_types; self.foreign_types(TOP_LEVEL_LOADER); end
+    def self.saver_types;  self.foreign_types(TOP_LEVEL_SAVER);  end
+
+    private
+
+    # Helper method that returns an `Array[VipsType]` given a top-level `VipsType` and a filename, suffix, or `::CHECKING::YOU::OUT`.
+    def self.foreign_for(top_level, given)
+      search = case given
+      when Array then given
+      when ::CHECKING::YOU::OUT then Array[given]
+      when String then given.include?('/'.freeze) ? Array[::CHECKING::YOU::OUT::from_ietf_media_type(given)] : ::CHECKING::YOU::OUT(given)
+      end
+      self.new(top_level).family_reunion.select { |vt| vt.types&.intersection(search)&.length&.method(:>)&.call(0) }
+    end
+
+    # Helper method that returns a Hash[CHECKING::YOU::OUT] => Set[VipsType] given a top-level VipsType.
+    def self.foreign_types(top_level)
+      self.new(top_level).family_reunion.each_with_object(
+        Hash.new { |h,k| h[k] = Set.new }
+      ) { |operation, types|
+        next if operation.types.nil?
+        operation.types.each { |type| types[type].add(operation) }
+      }
+    end
+
+    # Returns a default value (type variable) given a GParamSpec
+    def self.get_argument_default(param_spec)
+      begin
+        default_pointer = GObject::g_param_spec_get_default_value(param_spec)
+        default = GObject::GValue.new(default_pointer)
+        return nil if default.null?
+        return default.get
+      rescue ::FFI::NullPointerError => npe
+        # For some reason the :null? check doesn't catch NPEs from `get_array_of_float64`
+        # which I think is the GBoxed GType like VipsArrayDouble
+        nil
+      end
+    end
+
+    # Returns a Range, Enumerable, Class, or other value constraint.
+    def self.get_argument_valid_values(param_spec)
+      # HACK: Define Ranges manually until I figure out how to introspect them.
+      if VIPS_VALID.has_key?(param_spec[:name].to_sym)
+        return VIPS_VALID[param_spec[:name].to_sym]
+      end
+
+      return case GObject::g_type_fundamental(param_spec[:value_type])
+      when GObject::GENUM_TYPE
+        # I think the """proper""" way to do this is with gobject-introspection,
+        # but it's way simpler for now to just iterate until we find the terminating NULL.
+        Set.new.tap { |values|
+          loop.with_index { |_, i|
+            value = Vips::vips_enum_nick(param_spec[:value_type], i)
+            break if value == '(null)'.freeze or i > 33  # Safety factor in case the String ever differs
+            values.add(value)
+          }
+        }.map(&:to_sym)  # TODO: Fix value aliasing
+      when GObject::GBOOL_TYPE then Set[false, true]
+      when GObject::GDOUBLE_TYPE then Float
+      when GObject::GINT_TYPE then Integer
+      when GObject::GUINT64_TYPE then Integer
+      when GObject::GBOXED_TYPE then nil  #  TODO: Something besides nil
+      else nil
+      end
+    end
+
+  end  # VipsType Struct
+
+
+end

data/lib/distorted-floor/modular_technology/vips/save.rb

@@ -0,0 +1,135 @@
+require 'set'
+
+require 'distorted-floor/checking_you_out'
+using ::DistorteD::CHECKING::YOU::OUT
+
+require 'distorted-floor/modular_technology/vips/operation'
+
+
+module Cooltrainer; end
+module Cooltrainer::DistorteD; end
+module Cooltrainer::DistorteD::Technology; end
+module Cooltrainer::DistorteD::Technology::Vips::Save
+
+
+  # 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 via the usual libraries:
+  # - 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.
+  # - 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 based on String file suffixes defined in Saver C code.
+  # 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"]
+  #
+  # Vips chooses Loader modules, on the other hand, 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)
+  # but are nowhere to be found in the Saver-based `:get_suffixes`:
+  # https://github.com/libvips/ruby-vips/issues/186
+  OUTER_LIMITS = Cooltrainer::DistorteD::Technology::Vips::VipsType::saver_types.keep_if { |type, _operations|
+    # Skip textual formats like CVSV image data, and skip mistakenly-detected font Types.
+    #
+    # Suffix-based Loader detection with the `mime-types` library/database we use
+    # causes us to detect a Netpbm PortableFloatmap as an Adobe Printer Font Metrics file:
+    # https://en.wikipedia.org/wiki/Netpbm#32-bit_extensions
+    !type.to_s.include?(-'text') and !type.to_s.include?(-'font')
+  }.transform_values { |v| v.map(&:options).reduce(&:merge) }
+
+  # Define a to_<mediatype>_<subtype> method for each `::CHECKING::YOU::OUT` 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_key { |t|
+    next if t.nil?
+    define_method(t.distorted_file_method) { |dest_root, change|
+      # Find a VipsType Struct for the saver operation
+      vips_operation = Cooltrainer::DistorteD::Technology::Vips::VipsType::saver_for(change.type).first
+
+      # Prepare a Hash of options appropriate for this operation.
+      # We explicitly declare all supported VipsArguments, using the FFI-detected
+      # default values for keys with no user-given value.
+      options = change.to_hash.slice(
+        # Get an Array[Symbol] of non-aliased option keys.
+        # Loading any aliases' values happens when the Change/Atoms are constructed.
+        *vips_operation.options.keep_if { |aka, compound| aka == compound.element }.keys
+      ).reject { |k,v|
+        # Skip options we manually added (like :crop) or ones with nil values.
+        # TODO: Handle all VipsOperation arguments (like :crop) automatically.
+        [k == :crop, v.nil?].any?
+      }.transform_keys { |k|
+        # The `ruby-vips` binding expects hyphenated argument names to be converted to underscores:
+        # https://github.com/libvips/ruby-vips/blob/4f696e30796adcc99cbc70ff7fd778439f0cbac7/lib/vips/operation.rb#L78-L80
+        k.to_s.gsub('-', '_').to_sym
+      }
+
+      # HACK: MagickSave needs us to specify the 'delegate' (ImageMagick-speak)
+      # via the :format VipsAttribute that we skipped when generating Compounds.
+      # TODO: Use VipsType#parents once it exists instead of checking :include? on a String.
+      # TODO: Choose the delegate more directly/intelligently than by just downcasing the type,
+      # e.g. 'GIF -> 'gif'. It does work, but this seems fragile.
+      if vips_operation.to_s.include?('VipsForeignSaveMagick')
+        options.store(:format, change.type.genus.downcase)
+      end
+
+      loaded_image = to_vips_image(change)
+
+      # Assume the first destination_path has a :nil limit-break.
+      change.paths(dest_root).zip(Array[nil].concat(change.breaks)).each { |(dest_path, width)|
+        # Chain a call to VipsThumbnailImage into our input Vips::Image iff we were given a width.
+        # TODO: Exand this to aarbitrary other operations and consume their options Hash e.g.
+        # Cooltrainer::DistorteD::Technology::Vips::VipsType.new(:VipsThumbnailImage).options
+        input_image = (width or not [nil, :none].include?(change.to_hash.fetch(:crop, nil))) ?
+          loaded_image.thumbnail_image(loaded_image.width, crop: change.to_hash.fetch(:crop, :none)) :
+          loaded_image
+        # Do the thing.
+        Vips::Operation.call(
+          # `:vips_call` expects the operation_name to be a String:
+          # https://libvips.github.io/libvips/API/current/VipsOperation.html#vips-call
+          vips_operation.name.to_s,
+          # Write what Vips::Image, to where?
+          [input_image, dest_path],
+          # Operation-appropriate options Hash
+          options,
+          # `:options_string`, unused since we have everything in our Hash.
+          ''.freeze,
+        )
+      }
+
+      # Vips::Image#write_gc is a private method, but the built-in
+      # :write_to_file/:write_to_buffer methods call it, so we should call it too.
+      loaded_image.send(:write_gc)
+    }
+  }
+
+end

data/lib/distorted-floor/modular_technology/vips.rb

@@ -0,0 +1,17 @@
+require 'set'
+
+require 'distorted-floor/checking_you_out'
+
+require 'distorted-floor/modular_technology/vips/load'
+require 'distorted-floor/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::Vips::Save
+  include Cooltrainer::DistorteD::Technology::Vips::Load
+
+end