vips 8.8.4 → 8.12.1

data/lib/vips/image.rb

@@ -4,16 +4,19 @@
 # Author::    John Cupitt  (mailto:jcupitt@gmail.com)
 # License::   MIT
 
-require 'ffi'
+require "ffi"
 
 module Vips
   private
 
   attach_function :vips_image_new_matrix_from_array,
-      [:int, :int, :pointer, :int], :pointer
+    [:int, :int, :pointer, :int], :pointer
 
   attach_function :vips_image_copy_memory, [:pointer], :pointer
 
+  attach_function :vips_image_set_progress, [:pointer, :bool], :void
+  attach_function :vips_image_set_kill, [:pointer, :bool], :void
+
   attach_function :vips_filename_get_filename, [:string], :pointer
   attach_function :vips_filename_get_options, [:string], :pointer
 
@@ -22,30 +25,35 @@ module Vips
   attach_function :vips_foreign_find_load_buffer, [:pointer, :size_t], :string
   attach_function :vips_foreign_find_save_buffer, [:string], :string
 
+  if Vips.at_least_libvips?(8, 9)
+    attach_function :vips_foreign_find_load_source, [:pointer], :string
+    attach_function :vips_foreign_find_save_target, [:string], :string
+  end
+
   attach_function :vips_image_write_to_memory,
-      [:pointer, SizeStruct.ptr], :pointer
+    [:pointer, SizeStruct.ptr], :pointer
 
   attach_function :vips_image_get_typeof, [:pointer, :string], :GType
   attach_function :vips_image_get,
-      [:pointer, :string, GObject::GValue.ptr], :int
+    [:pointer, :string, GObject::GValue.ptr], :int
+
+  attach_function :vips_image_get_width, [:pointer], :int
+  attach_function :vips_image_get_height, [:pointer], :int
+  attach_function :vips_image_get_bands, [:pointer], :int
 
-  # vips_image_get_fields was added in libvips 8.5
-  begin
+  if Vips.at_least_libvips?(8, 5)
     attach_function :vips_image_get_fields, [:pointer], :pointer
-  rescue FFI::NotFoundError
-    nil
+    attach_function :vips_image_hasalpha, [:pointer], :int
   end
 
-  # vips_addalpha was added in libvips 8.6
-  if Vips::at_least_libvips?(8, 6)
+  if Vips.at_least_libvips?(8, 6)
     attach_function :vips_addalpha, [:pointer, :pointer, :varargs], :int
   end
-  if Vips::at_least_libvips?(8, 5)
-    attach_function :vips_image_hasalpha, [:pointer], :int
-  end
 
+  # move these three lines to mutableimage when we finally remove set and
+  # remove in this class
   attach_function :vips_image_set,
-      [:pointer, :string, GObject::GValue.ptr], :void
+    [:pointer, :string, GObject::GValue.ptr], :void
   attach_function :vips_image_remove, [:pointer, :string], :void
 
   attach_function :vips_band_format_iscomplex, [:int], :int
@@ -53,6 +61,11 @@ module Vips
 
   attach_function :nickname_find, :vips_nickname_find, [:GType], :string
 
+  attach_function :vips_image_invalidate_all, [:pointer], :void
+
+  attach_function :vips_image_new_from_memory, [:pointer, :size_t, :int, :int, :int, :int], :pointer
+  attach_function :vips_image_new_from_memory_copy, [:pointer, :size_t, :int, :int, :int, :int], :pointer
+
   # turn a raw pointer that must be freed into a self-freeing Ruby string
   def self.p2str(pointer)
     pointer = FFI::AutoPointer.new(pointer, GLib::G_FREE)
@@ -67,6 +80,15 @@ module Vips
   class Image < Vips::Object
     alias_method :parent_get_typeof, :get_typeof
 
+    def close
+      Vips.vips_image_invalidate_all(self)
+    end
+
+    # FFI sets a pointer's size to this magic value if the size of the memory
+    # chunk the pointer points to is unknown to FFI.
+    UNKNOWN_POINTER_SIZE = FFI::Pointer.new(1).size
+    private_constant :UNKNOWN_POINTER_SIZE
+
     private
 
     # the layout of the VipsImage struct
@@ -94,17 +116,17 @@ module Vips
     # handy for overloads ... want to be able to apply a function to an
     # array or to a scalar
     def self.smap x, &block
-      x.is_a?(Array) ? x.map { |y| smap(y, &block) } : block.(x)
+      x.is_a?(Array) ? x.map { |y| smap(y, &block) } : block.call(x)
     end
 
     def self.complex? format
       format_number = GObject::GValue.from_nick BAND_FORMAT_TYPE, format
-      Vips::vips_band_format_iscomplex(format_number) != 0
+      Vips.vips_band_format_iscomplex(format_number) != 0
     end
 
     def self.float? format
       format_number = GObject::GValue.from_nick BAND_FORMAT_TYPE, format
-      Vips::vips_band_format_isfloat(format_number) != 0
+      Vips.vips_band_format_isfloat(format_number) != 0
     end
 
     # run a complex operation on a complex image, or an image with an even
@@ -113,12 +135,12 @@ module Vips
     def self.run_cmplx image, &block
       original_format = image.format
 
-      unless Image::complex? image.format
+      unless Image.complex? image.format
         if image.bands % 2 != 0
-          raise Error, "not an even number of bands"
+          raise Vips::Error, "not an even number of bands"
         end
 
-        unless Image::float? image.format
+        unless Image.float? image.format
           image = image.cast :float
         end
 
@@ -126,9 +148,9 @@ module Vips
         image = image.copy format: new_format, bands: image.bands / 2
       end
 
-      image = block.(image)
+      image = block.call(image)
 
-      unless Image::complex? original_format
+      unless Image.complex? original_format
         new_format = image.format == :dpcomplex ? :double : :float
         image = image.copy format: new_format, bands: image.bands * 2
       end
@@ -145,34 +167,6 @@ module Vips
       end
     end
 
-    # Write can fail due to no file descriptors and memory can fill if
-    # large objects are not collected fairly soon. We can't try a
-    # write and GC and retry on fail, since the write may take a
-    # long time and may not be repeatable.
-    #
-    # GCing before every write would have a horrible effect on
-    # performance, so as a compromise we GC every @@gc_interval writes.
-    #
-    # ruby2.1 introduced a generational GC which is fast enough to be
-    # able to GC on every write.
-
-    @@generational_gc = RUBY_ENGINE == "ruby" && RUBY_VERSION.to_f >= 2.1
-
-    @@gc_interval = 100
-    @@gc_countdown = @@gc_interval
-
-    def write_gc
-      if @@generational_gc
-        GC.start full_mark: false
-      else
-        @@gc_countdown -= 1
-        if @@gc_countdown < 0
-          @@gc_countdown = @@gc_interval
-          GC.start
-        end
-      end
-    end
-
     public
 
     def inspect
@@ -187,15 +181,19 @@ module Vips
       #   36013-heads-up-ruby-implicitly-converts-a-hash-to-keyword-arguments
       return false if name == :to_hash
 
+      super
+    end
+
+    def respond_to_missing? name, include_all = false
       # respond to all vips operations by nickname
-      return true if Vips::type_find("VipsOperation", name.to_s) != 0
+      return true if Vips.type_find("VipsOperation", name.to_s) != 0
 
       super
     end
 
-    def self.respond_to? name, include_all = false
+    def self.respond_to_missing? name, include_all = false
       # respond to all vips operations by nickname
-      return true if Vips::type_find("VipsOperation", name.to_s) != 0
+      return true if Vips.type_find("VipsOperation", name.to_s) != 0
 
       super
     end
@@ -219,13 +217,13 @@ module Vips
     # load options, for example:
     #
     # ```
-    # image = Vips::new_from_file "fred.jpg[shrink=2]"
+    # image = Vips::Image.new_from_file "fred.jpg[shrink=2]"
     # ```
     #
     # You can also supply options as a hash, for example:
     #
     # ```
-    # image = Vips::new_from_file "fred.jpg", shrink: 2
+    # image = Vips::Image.new_from_file "fred.jpg", shrink: 2
     # ```
     #
     # The full set of options available depend upon the load operation that
@@ -253,18 +251,18 @@ module Vips
     def self.new_from_file name, **opts
       # very common, and Vips::vips_filename_get_filename will segv if we
       # pass this
-      raise Vips::Error, "filename is nil" if name == nil
+      raise Vips::Error, "filename is nil" if name.nil?
 
-      filename = Vips::p2str(Vips::vips_filename_get_filename name)
-      option_string = Vips::p2str(Vips::vips_filename_get_options name)
-      loader = Vips::vips_foreign_find_load filename
-      raise Vips::Error if loader == nil
+      filename = Vips.p2str(Vips.vips_filename_get_filename(name))
+      option_string = Vips.p2str(Vips.vips_filename_get_options(name))
+      loader = Vips.vips_foreign_find_load filename
+      raise Vips::Error if loader.nil?
 
       Operation.call loader, [filename], opts, option_string
     end
 
-    # Create a new {Image} for an image encoded, in a format such as
-    # JPEG, in a binary string. Load options may be passed as
+    # Create a new {Image} for an image encoded in a format such as
+    # JPEG in a binary string. Load options may be passed as
     # strings or appended as a hash. For example:
     #
     # ```
@@ -295,17 +293,157 @@ module Vips
     # @macro vips.loadopts
     # @return [Image] the loaded image
     def self.new_from_buffer data, option_string, **opts
-      loader = Vips::vips_foreign_find_load_buffer data, data.bytesize
-      raise Vips::Error if loader == nil
+      loader = Vips.vips_foreign_find_load_buffer data, data.bytesize
+      raise Vips::Error if loader.nil?
 
       Vips::Operation.call loader, [data], opts, option_string
     end
 
+    # Create a new {Image} from a C-style array held in memory. For example:
+    #
+    # ```
+    # image = Vips::Image.black(16, 16) + 128
+    # data = image.write_to_memory
+    #
+    # x = Vips::Image.new_from_memory data,
+    #   image.width, image.height, image.bands, image.format
+    # ```
+    #
+    # Creating a new image from a memory pointer:
+    #
+    # ```
+    # ptr = FFI::MemoryPointer.new(:uchar, 10*10)
+    # # => #<FFI::MemoryPointer address=0x00007fc236db31d0 size=100>
+    # x = Vips::Image.new_from_memory(ptr, 10, 10, 1, :uchar)
+    # ```
+    #
+    # Creating a new image from an address only pointer:
+    #
+    # ```
+    # ptr = call_to_external_c_library(w: 10, h: 10)
+    # # => #<FFI::Pointer address=0x00007f9780813a00>
+    # ptr_slice = ptr.slice(0, 10*10)
+    # # => #<FFI::Pointer address=0x00007f9780813a00 size=100>
+    # x = Vips::Image.new_from_memory(ptr_slice, 10, 10, 1, :uchar)
+    # ```
+    #
+    # {new_from_memory} keeps a reference to the array of pixels you pass in
+    # to try to prevent that memory from being freed by the Ruby GC while it
+    # is being used.
+    #
+    # See {new_from_memory_copy} for a version of this method which does not
+    # keep a reference.
+    #
+    # @param data [String, FFI::Pointer] the data to load from
+    # @param width [Integer] width in pixels
+    # @param height [Integer] height in pixels
+    # @param bands [Integer] number of bands
+    # @param format [Symbol] band format
+    # @return [Image] the loaded image
+    def self.new_from_memory data, width, height, bands, format
+      # prevent data from being freed with JRuby FFI
+      if defined?(JRUBY_VERSION) && !data.is_a?(FFI::Pointer)
+        data = ::FFI::MemoryPointer.new(:char, data.bytesize).write_bytes data
+      end
+
+      if data.is_a?(FFI::Pointer)
+        # A pointer needs to know about the size of the memory it points to.
+        # If you have an address-only pointer, use the .slice method to wrap
+        # the pointer in a size aware pointer.
+        if data.size == UNKNOWN_POINTER_SIZE
+          raise Vips::Error, "size of memory is unknown"
+        end
+        size = data.size
+      else
+        size = data.bytesize
+      end
+
+      format_number = GObject::GValue.from_nick BAND_FORMAT_TYPE, format
+      vi = Vips.vips_image_new_from_memory data, size,
+        width, height, bands, format_number
+      raise Vips::Error if vi.null?
+      image = new(vi)
+
+      # keep a secret ref to the underlying object .. this reference will be
+      # inherited by things that in turn depend on us, so the memory we are
+      # using will not be freed
+      image.references << data
+
+      image
+    end
+
+    # Create a new {Image} from memory and copies the memory area. See
+    # {new_from_memory} for a version of this method which does not copy the
+    # memory area.
+    #
+    # @param data [String, FFI::Pointer] the data to load from
+    # @param width [Integer] width in pixels
+    # @param height [Integer] height in pixels
+    # @param bands [Integer] number of bands
+    # @param format [Symbol] band format
+    # @return [Image] the loaded image
+    def self.new_from_memory_copy data, width, height, bands, format
+      format_number = GObject::GValue.from_nick BAND_FORMAT_TYPE, format
+
+      if data.is_a?(FFI::Pointer)
+        if data.size == UNKNOWN_POINTER_SIZE
+          raise Vips::Error, "size of memory is unknown"
+        end
+        size = data.size
+      else
+        size = data.bytesize
+      end
+
+      vi = Vips.vips_image_new_from_memory_copy data, size,
+        width, height, bands, format_number
+      raise Vips::Error if vi.null?
+      new(vi)
+    end
+
+    # Create a new {Image} from a source. Load options may be passed as
+    # strings or appended as a hash. For example:
+    #
+    # ```
+    # source = Vips::Source.new_from_file("k2.jpg")
+    # image = Vips::Image.new_from_source source, "shrink=2"
+    # ```
+    #
+    # or alternatively:
+    #
+    # ```
+    # image = Vips::Image.new_from_source source, "", shrink: 2
+    # ```
+    #
+    # The options available depend on the file format. Try something like:
+    #
+    # ```
+    # $ vips jpegload_source
+    # ```
+    #
+    # at the command-line to see the available options. Not all loaders
+    # support load from source, but at least JPEG, PNG and
+    # TIFF images will work.
+    #
+    # Loading is fast: only enough data is read to be able to fill
+    # out the header. Pixels will only be read and decompressed when they are
+    # needed.
+    #
+    # @param source [Vips::Source] the source to load from
+    # @param option_string [String] load options as a string
+    # @macro vips.loadopts
+    # @return [Image] the loaded image
+    def self.new_from_source source, option_string, **opts
+      loader = Vips.vips_foreign_find_load_source source
+      raise Vips::Error if loader.nil?
+
+      Vips::Operation.call loader, [source], opts, option_string
+    end
+
     def self.matrix_from_array width, height, array
       ptr = FFI::MemoryPointer.new :double, array.length
       ptr.write_array_of_double array
-      image = Vips::vips_image_new_matrix_from_array width, height,
-          ptr, array.length
+      image = Vips.vips_image_new_matrix_from_array width, height,
+        ptr, array.length
       Vips::Image.new image
     end
 
@@ -317,13 +455,13 @@ module Vips
     # For example:
     #
     # ```
-    # image = Vips::new_from_array [1, 2, 3]
+    # image = Vips::Image.new_from_array [1, 2, 3]
     # ```
     #
     # or
     #
     # ```
-    # image = Vips::new_from_array [
+    # image = Vips::Image.new_from_array [
     #     [-1, -1, -1],
     #     [-1, 16, -1],
     #     [-1, -1, -1]], 8
@@ -358,18 +496,22 @@ module Vips
         width = array.length
       end
 
+      unless array.length == width * height
+        raise Vips::Error, "Bad array dimensions."
+      end
+
       unless array.all? { |x| x.is_a? Numeric }
         raise Vips::Error, "Not all array elements are Numeric."
       end
 
       image = Vips::Image.matrix_from_array width, height, array
-      raise Vips::Error if image == nil
+      raise Vips::Error if image.nil?
 
-      # be careful to set them as double
-      image.set_type GObject::GDOUBLE_TYPE, 'scale', scale.to_f
-      image.set_type GObject::GDOUBLE_TYPE, 'offset', offset.to_f
-
-      return image
+      image.mutate do |mutable|
+        # be careful to set them as double
+        mutable.set_type! GObject::GDOUBLE_TYPE, "scale", scale.to_f
+        mutable.set_type! GObject::GDOUBLE_TYPE, "offset", offset.to_f
+      end
     end
 
     # A new image is created with the same width, height, format,
@@ -418,16 +560,16 @@ module Vips
     #
     # @param name [String] filename to write to
     def write_to_file name, **opts
-      filename = Vips::p2str(Vips::vips_filename_get_filename name)
-      option_string = Vips::p2str(Vips::vips_filename_get_options name)
-      saver = Vips::vips_foreign_find_save filename
-      if saver == nil
-        raise Vips::Error, "No known saver for '#{filename}'."
-      end
+      raise Vips::Error, "filename is nil" if name.nil?
+
+      filename = Vips.p2str(Vips.vips_filename_get_filename(name))
+      option_string = Vips.p2str(Vips.vips_filename_get_options(name))
+      saver = Vips.vips_foreign_find_save filename
+      raise Vips::Error if saver.nil?
 
       Vips::Operation.call saver, [self, filename], opts, option_string
 
-      write_gc
+      GC.start(full_mark: false)
     end
 
     # Write this image to a memory buffer. Save options may be encoded in
@@ -456,33 +598,112 @@ module Vips
     # @macro vips.saveopts
     # @return [String] the image saved in the specified format
     def write_to_buffer format_string, **opts
-      filename = Vips::p2str(Vips::vips_filename_get_filename format_string)
-      option_string = Vips::p2str(Vips::vips_filename_get_options format_string)
-      saver = Vips::vips_foreign_find_save_buffer filename
-      if saver == nil
-        raise Vips::Error, "No known saver for '#{filename}'."
+      raise Vips::Error, "filename is nil" if format_string.nil?
+      filename = Vips.p2str(Vips.vips_filename_get_filename(format_string))
+      option_string = Vips.p2str(Vips.vips_filename_get_options(format_string))
+
+      # try to save with the new target API first, only fall back to the old
+      # buffer API if there's no target save for this filetype
+      saver = nil
+      if Vips.at_least_libvips?(8, 9)
+        Vips.vips_error_freeze
+        saver = Vips.vips_foreign_find_save_target filename
+        Vips.vips_error_thaw
       end
 
-      buffer = Vips::Operation.call saver, [self], opts, option_string
-      raise Vips::Error if buffer == nil
+      if !saver.nil?
+        target = Vips::Target.new_to_memory
+        Vips::Operation.call saver, [self, target], opts, option_string
+        buffer = target.get("blob")
+      else
+        saver = Vips.vips_foreign_find_save_buffer filename
+        raise Vips::Error if saver.nil?
+
+        buffer = Vips::Operation.call saver, [self], opts, option_string
+        raise Vips::Error if buffer.nil?
+      end
 
-      write_gc
+      GC.start(full_mark: false)
 
       return buffer
     end
 
+    # Write this image to a target. Save options may be encoded in
+    # the format_string or given as a hash. For example:
+    #
+    # ```ruby
+    # target = Vips::Target.new_to_file "k2.jpg"
+    # image.write_to_target target, ".jpg[Q=90]"
+    # ```
+    #
+    # or equivalently:
+    #
+    # ```ruby
+    # image.write_to_target target, ".jpg", Q: 90
+    # ```
+    #
+    # The full set of save options depend on the selected saver. Try
+    # something like:
+    #
+    # ```
+    # $ vips jpegsave_target
+    # ```
+    #
+    # to see all the available options for JPEG save.
+    #
+    # @param target [Vips::Target] the target to write to
+    # @param format_string [String] save format plus string options
+    # @macro vips.saveopts
+    def write_to_target target, format_string, **opts
+      raise Vips::Error, "filename is nil" if format_string.nil?
+      filename = Vips.p2str(Vips.vips_filename_get_filename(format_string))
+      option_string = Vips.p2str(Vips.vips_filename_get_options(format_string))
+      saver = Vips.vips_foreign_find_save_target filename
+      raise Vips::Error if saver.nil?
+
+      Vips::Operation.call saver, [self, target], opts, option_string
+
+      GC.start(full_mark: false)
+    end
+
     # Write this image to a large memory buffer.
     #
     # @return [String] the pixels as a huge binary string
     def write_to_memory
       len = Vips::SizeStruct.new
-      ptr = Vips::vips_image_write_to_memory self, len
-      raise Vips::Error if ptr == nil
+      ptr = Vips.vips_image_write_to_memory self, len
+      raise Vips::Error if ptr.nil?
 
       # wrap up as an autopointer
       ptr = FFI::AutoPointer.new(ptr, GLib::G_FREE)
 
-      ptr.get_bytes 0, len[:value]
+      data = ptr.get_bytes 0, len[:value]
+
+      GC.start(full_mark: false)
+
+      return data
+    end
+
+    # Turn progress signalling on and off.
+    #
+    # If this is on, the most-downstream image from this image will issue
+    # progress signals.
+    #
+    # @see Object#signal_connect
+    # @param state [Boolean] progress signalling state
+    def set_progress state
+      Vips.vips_image_set_progress self, state
+    end
+
+    # Kill computation of this time.
+    #
+    # Set true to stop computation of this image. You can call this from a
+    # progress handler, for example.
+    #
+    # @see Object#signal_connect
+    # @param kill [Boolean] stop computation
+    def set_kill kill
+      Vips.vips_image_set_kill self, kill
     end
 
     # Get the `GType` of a metadata field. The result is 0 if no such field
@@ -494,12 +715,12 @@ module Vips
     def get_typeof name
       # on libvips before 8.5, property types must be searched first,
       # since vips_image_get_typeof returned built-in enums as int
-      unless Vips::at_least_libvips?(8, 5)
+      unless Vips.at_least_libvips?(8, 5)
         gtype = parent_get_typeof name
         return gtype if gtype != 0
       end
 
-      Vips::vips_image_get_typeof self, name
+      Vips.vips_image_get_typeof self, name
     end
 
     # Get a metadata item from an image. Ruby types are constructed
@@ -518,15 +739,16 @@ module Vips
     def get name
       # with old libvips, we must fetch properties (as opposed to
       # metadata) via VipsObject
-      unless Vips::at_least_libvips?(8, 5)
+      unless Vips.at_least_libvips?(8, 5)
         return super if parent_get_typeof(name) != 0
       end
 
       gvalue = GObject::GValue.alloc
-      result = Vips::vips_image_get self, name, gvalue
-      raise Vips::Error if result != 0
+      raise Vips::Error if Vips.vips_image_get(self, name, gvalue) != 0
+      result = gvalue.get
+      gvalue.unset
 
-      gvalue.get
+      result
     end
 
     # Get the names of all fields on an image. Use this to loop over all
@@ -537,66 +759,64 @@ module Vips
       # vips_image_get_fields() was added in libvips 8.5
       return [] unless Vips.respond_to? :vips_image_get_fields
 
-      array = Vips::vips_image_get_fields self
+      array = Vips.vips_image_get_fields self
 
       names = []
       p = array
       until (q = p.read_pointer).null?
         names << q.read_string
-        GLib::g_free q
+        GLib.g_free q
         p += FFI::Type::POINTER.size
       end
-      GLib::g_free array
+      GLib.g_free array
 
       names
     end
 
-    # Create a metadata item on an image of the specifed type. Ruby types
-    # are automatically transformed into the matching `GType`, if possible.
+    # Mutate an image with a block. Inside the block, you can call methods
+    # which modify the image, such as setting or removing metadata, or
+    # modifying pixels.
     #
-    # For example, you can use this to set an image's ICC profile:
+    # For example:
     #
-    # ```
-    # x = y.set_type Vips::BLOB_TYPE, "icc-profile-data", profile
+    # ```ruby
+    # image = image.mutate do |x|
+    #   (0 ... 1).step(0.01) do |i|
+    #     x.draw_line! 255, x.width * i, 0, 0, x.height * (1 - i)
+    #   end
+    # end
     # ```
     #
-    # where `profile` is an ICC profile held as a binary string object.
+    # See {MutableImage}.
+    def mutate
+      mutable = Vips::MutableImage.new self
+      yield mutable
+      mutable.image
+    end
+
+    # This method is deprecated.
     #
-    # @see set
-    # @param gtype [Integer] GType of item
-    # @param name [String] Metadata field to set
-    # @param value [Object] Value to set
+    # Please use {MutableImage#set_type!} instead.
     def set_type gtype, name, value
       gvalue = GObject::GValue.alloc
       gvalue.init gtype
       gvalue.set value
-      Vips::vips_image_set self, name, gvalue
+      Vips.vips_image_set self, name, gvalue
+      gvalue.unset
     end
 
-    # Set the value of a metadata item on an image. The metadata item must
-    # already exist. Ruby types are automatically transformed into the
-    # matching `GValue`, if possible.
-    #
-    # For example, you can use this to set an image's ICC profile:
-    #
-    # ```
-    # x = y.set "icc-profile-data", profile
-    # ```
-    #
-    # where `profile` is an ICC profile held as a binary string object.
+    # This method is deprecated.
     #
-    # @see set_type
-    # @param name [String] Metadata field to set
-    # @param value [Object] Value to set
+    # Please use {MutableImage#set!} instead.
     def set name, value
       set_type get_typeof(name), name, value
     end
 
-    # Remove a metadata item from an image.
+    # This method is deprecated.
     #
-    # @param name [String] Metadata field to remove
+    # Please use {MutableImage#remove!} instead.
     def remove name
-      Vips::vips_image_remove self, name
+      Vips.vips_image_remove self, name
     end
 
     # compatibility: old name for get
@@ -604,7 +824,9 @@ module Vips
       get name
     end
 
-    # compatibility: old name for set
+    # This method is deprecated.
+    #
+    # Please use {MutableImage#set!} instead.
     def set_value name, value
       set name, value
     end
@@ -613,21 +835,21 @@ module Vips
     #
     # @return [Integer] image width, in pixels
     def width
-      get "width"
+      Vips.vips_image_get_width self
     end
 
     # Get image height, in pixels.
     #
     # @return [Integer] image height, in pixels
     def height
-      get "height"
+      Vips.vips_image_get_height self
     end
 
     # Get number of image bands.
     #
     # @return [Integer] number of image bands
     def bands
-      get "bands"
+      Vips.vips_image_get_bands self
     end
 
     # Get image format.
@@ -711,23 +933,23 @@ module Vips
       [width, height]
     end
 
-    if Vips::at_least_libvips?(8, 5)
+    if Vips.at_least_libvips?(8, 5)
       # Detect if image has an alpha channel
       #
       # @return [Boolean] true if image has an alpha channel.
       def has_alpha?
-        return Vips::vips_image_hasalpha(self) != 0
+        Vips.vips_image_hasalpha(self) != 0
       end
     end
 
     # vips_addalpha was added in libvips 8.6
-    if Vips::at_least_libvips?(8, 6)
+    if Vips.at_least_libvips?(8, 6)
       # Append an alpha channel to an image.
       #
       # @return [Image] new image
       def add_alpha
         ptr = GenericPtr.new
-        result = Vips::vips_addalpha self, ptr
+        result = Vips.vips_addalpha self, ptr
         raise Vips::Error if result != 0
 
         Vips::Image.new ptr[:value]
@@ -742,7 +964,7 @@ module Vips
     #
     # @return [Image] new memory image
     def copy_memory
-      new_image = Vips::vips_image_copy_memory self
+      new_image = Vips.vips_image_copy_memory self
       Vips::Image.new new_image
     end
 
@@ -752,7 +974,7 @@ module Vips
     #
     # @return [Image] modified image
     def draw_point ink, left, top, **opts
-      draw_rect ink, left, top, 1, 1, opts
+      draw_rect ink, left, top, 1, 1, **opts
     end
 
     # Add an image, constant or array.
@@ -770,7 +992,7 @@ module Vips
     # @return [Image] result of subtraction
     def - other
       other.is_a?(Vips::Image) ?
-          subtract(other) : linear(1, Image::smap(other) { |x| x * -1 })
+          subtract(other) : linear(1, Image.smap(other) { |x| x * -1 })
     end
 
     # Multiply an image, constant or array.
@@ -788,7 +1010,7 @@ module Vips
     # @return [Image] result of division
     def / other
       other.is_a?(Vips::Image) ?
-          divide(other) : linear(Image::smap(other) { |x| 1.0 / x }, 0)
+          divide(other) : linear(Image.smap(other) { |x| 1.0 / x }, 0)
     end
 
     # Remainder after integer division with an image, constant or array.
@@ -914,7 +1136,7 @@ module Vips
     # @return [Image] result of equality
     def == other
       # for equality, we must allow tests against nil
-      if other == nil
+      if other.nil?
         false
       else
         call_enum "relational", other, :equal
@@ -927,7 +1149,7 @@ module Vips
     # @return [Image] result of inequality
     def != other
       # for equality, we must allow tests against nil
-      if other == nil
+      if other.nil?
         true
       else
         call_enum "relational", other, :noteq
@@ -949,38 +1171,40 @@ module Vips
       end
     end
 
-    # Convert to an Array. This will be slow for large images.
+    # Convert to an Enumerator. Similar to `#to_a` but lazier.
     #
-    # @return [Array] array of Fixnum
-    def to_a
-      # we render the image to a big string, then unpack
-      # as a Ruby array of the correct type
-      memory = write_to_memory
-
+    # @return [Enumerator] Enumerator of Enumerators of Arrays of Numerics
+    def to_enum
       # make the template for unpack
       template = {
-        char: 'c',
-        uchar: 'C',
-        short: 's_',
-        ushort: 'S_',
-        int: 'i_',
-        uint: 'I_',
-        float: 'f',
-        double: 'd',
-        complex: 'f',
-        dpcomplex: 'd'
-      }[format] + '*'
+        char: "c",
+        uchar: "C",
+        short: "s_",
+        ushort: "S_",
+        int: "i_",
+        uint: "I_",
+        float: "f",
+        double: "d",
+        complex: "f",
+        dpcomplex: "d"
+      }[format] + "*"
 
-      # and unpack into something like [1, 2, 3, 4 ..]
-      array = memory.unpack(template)
+      # we render the image to a big string, then unpack into
+      # one-dimensional array as a Ruby array of the correct type
+      array = write_to_memory.unpack template
 
-      # gather band elements together
-      pixel_array = array.each_slice(bands).to_a
+      # gather bands of a pixel together
+      pixel_array = array.each_slice bands
 
-      # build rows
-      row_array = pixel_array.each_slice(width).to_a
+      # gather pixels of a row together
+      pixel_array.each_slice width
+    end
 
-      return row_array
+    # Convert to an Array. This will be slow for large images.
+    #
+    # @return [Array] Array of Arrays of Arrays of Numerics
+    def to_a
+      to_enum.to_a
     end
 
     # Return the largest integral value not greater than the argument.
@@ -1056,10 +1280,13 @@ module Vips
     # @param overlay [Image, Array<Image>] images to composite
     # @param mode [BlendMode, Array<BlendMode>] blend modes to use
     # @param opts [Hash] Set of options
-    # @option opts [Vips::Interpretation] :compositing_space Composite images in this colour space
+    # @option opts [Array<Integer>] :x x positions of overlay
+    # @option opts [Array<Integer>] :y y positions of overlay
+    # @option opts [Vips::Interpretation] :compositing_space Composite images
+    #     in this colour space
     # @option opts [Boolean] :premultiplied Images have premultiplied alpha
     # @return [Image] blended image
-    def composite overlay, mode, **opts
+    def composite overlay, mode, **options
       unless overlay.is_a? Array
         overlay = [overlay]
       end
@@ -1071,7 +1298,7 @@ module Vips
         GObject::GValue.from_nick Vips::BLEND_MODE_TYPE, x
       end
 
-      Vips::Image.composite([self] + overlay, mode, opts)
+      Vips::Image.composite([self] + overlay, mode, **options)
     end
 
     # Return the coordinates of the image maximum.
@@ -1080,9 +1307,9 @@ module Vips
     #   coordinate of maximum
     def maxpos
       v, opts = max x: true, y: true
-      x = opts['x']
-      y = opts['y']
-      return v, x, y
+      x = opts["x"]
+      y = opts["y"]
+      [v, x, y]
     end
 
     # Return the coordinates of the image minimum.
@@ -1091,9 +1318,9 @@ module Vips
     #   coordinate of minimum
     def minpos
       v, opts = min x: true, y: true
-      x = opts['x']
-      y = opts['y']
-      return v, x, y
+      x = opts["x"]
+      y = opts["y"]
+      [v, x, y]
     end
 
     # a median filter
@@ -1101,7 +1328,7 @@ module Vips
     # @param size [Integer] size of filter window
     # @return [Image] result of median filter
     def median size = 3
-      rank size, size, (size * size) / 2
+      rank size, size, size**2 / 2
     end
 
     # Return the real part of a complex image.
@@ -1128,7 +1355,7 @@ module Vips
     # @see xyz
     # @return [Image] image converted to polar coordinates
     def polar
-      Image::run_cmplx(self) { |x| x.complex :polar }
+      Image.run_cmplx(self) { |x| x.complex :polar }
     end
 
     # Return an image with polar pixels converted to rectangular.
@@ -1141,7 +1368,7 @@ module Vips
     # @see xyz
     # @return [Image] image converted to rectangular coordinates
     def rect
-      Image::run_cmplx(self) { |x| x.complex :rect }
+      Image.run_cmplx(self) { |x| x.complex :rect }
     end
 
     # Return the complex conjugate of an image.
@@ -1153,7 +1380,7 @@ module Vips
     #
     # @return [Image] complex conjugate
     def conj
-      Image::run_cmplx(self) { |x| x.complex :conj }
+      Image.run_cmplx(self) { |x| x.complex :conj }
     end
 
     # Calculate the cross phase of two images.
@@ -1206,6 +1433,48 @@ module Vips
       math :atan
     end
 
+    # Return the hyperbolic sine of an image in radians.
+    #
+    # @return [Image] sine of each pixel
+    def sinh
+      math :sinh
+    end
+
+    # Return the hyperbolic cosine of an image in radians.
+    #
+    # @return [Image] cosine of each pixel
+    def cosh
+      math :cosh
+    end
+
+    # Return the hyperbolic tangent of an image in radians.
+    #
+    # @return [Image] tangent of each pixel
+    def tanh
+      math :tanh
+    end
+
+    # Return the inverse hyperbolic sine of an image in radians.
+    #
+    # @return [Image] inverse sine of each pixel
+    def asinh
+      math :asinh
+    end
+
+    # Return the inverse hyperbolic cosine of an image in radians.
+    #
+    # @return [Image] inverse cosine of each pixel
+    def acosh
+      math :acosh
+    end
+
+    # Return the inverse hyperbolic tangent of an image in radians.
+    #
+    # @return [Image] inverse tangent of each pixel
+    def atanh
+      math :atanh
+    end
+
     # Return the natural log of an image.
     #
     # @return [Image] natural log of each pixel
@@ -1320,30 +1589,27 @@ module Vips
     #
     # @param opts [Hash] Set of options
     # @return [Vips::Image] Output image
-    def scaleimage **opts
-      Vips::Image.scale self, opts
+    def scaleimage **options
+      Vips::Image.scale self, **options
     end
   end
 end
 
 module Vips
-  # This method generates yard comments for all the dynamically bound
+  # This module generates yard comments for all the dynamically bound
   # vips operations.
   #
   # Regenerate with something like:
   #
   # ```
   # $ ruby > methods.rb
-  # require 'vips'; Vips::generate_yard
+  # require "vips"; Vips::Yard.generate
   # ^D
   # ```
 
-  def self.generate_yard
-    # these have hand-written methods, see above
-    no_generate = ["scale", "bandjoin", "composite", "ifthenelse"]
-
+  module Yard
     # map gobject's type names to Ruby
-    map_go_to_ruby = {
+    MAP_GO_TO_RUBY = {
       "gboolean" => "Boolean",
       "gint" => "Integer",
       "gdouble" => "Float",
@@ -1351,109 +1617,92 @@ module Vips
       "gchararray" => "String",
       "VipsImage" => "Vips::Image",
       "VipsInterpolate" => "Vips::Interpolate",
+      "VipsConnection" => "Vips::Connection",
+      "VipsSource" => "Vips::Source",
+      "VipsTarget" => "Vips::Target",
+      "VipsSourceCustom" => "Vips::SourceCustom",
+      "VipsTargetCustom" => "Vips::TargetCustom",
       "VipsArrayDouble" => "Array<Double>",
       "VipsArrayInt" => "Array<Integer>",
       "VipsArrayImage" => "Array<Image>",
-      "VipsArrayString" => "Array<String>",
+      "VipsArrayString" => "Array<String>"
     }
 
-    generate_operation = lambda do |gtype, nickname, op|
-      op_flags = op.get_flags
-      return if (op_flags & OPERATION_DEPRECATED) != 0
-      return if no_generate.include? nickname
-
-      description = Vips::vips_object_get_description op
-
-      # find and classify all the arguments the operator can take
-      required_input = []
-      optional_input = []
-      required_output = []
-      optional_output = []
-      member_x = nil
-      op.argument_map do |pspec, argument_class, _argument_instance|
-        arg_flags = argument_class[:flags]
-        next if (arg_flags & ARGUMENT_CONSTRUCT) == 0
-        next if (arg_flags & ARGUMENT_DEPRECATED) != 0
-
-        name = pspec[:name].tr("-", "_")
-        # 'in' as a param name confuses yard
-        name = "im" if name == "in"
-        gtype = pspec[:value_type]
-        fundamental = GObject::g_type_fundamental gtype
-        type_name = GObject::g_type_name gtype
-        if map_go_to_ruby.include? type_name
-          type_name = map_go_to_ruby[type_name]
-        end
-        if fundamental == GObject::GFLAGS_TYPE ||
-           fundamental == GObject::GENUM_TYPE
-          type_name = "Vips::" + type_name[/Vips(.*)/, 1]
-        end
-        blurb = GObject::g_param_spec_get_blurb pspec
-        value = {
-          name: name,
-          flags: arg_flags,
-          gtype: gtype,
-          type_name: type_name,
-          blurb: blurb
-        }
-
-        if (arg_flags & ARGUMENT_INPUT) != 0
-          if (arg_flags & ARGUMENT_REQUIRED) != 0
-            # note the first required input image, if any ... we
-            # will be a method of this instance
-            if !member_x && gtype == Vips::IMAGE_TYPE
-              member_x = value
-            else
-              required_input << value
-            end
-          else
-            optional_input << value
-          end
-        end
+    # these have hand-written methods, see above
+    NO_GENERATE = ["scale", "bandjoin", "composite", "ifthenelse"]
 
-        # MODIFY INPUT args count as OUTPUT as well
-        if (arg_flags & ARGUMENT_OUTPUT) != 0 ||
-           ((arg_flags & ARGUMENT_INPUT) != 0 &&
-            (arg_flags & ARGUMENT_MODIFY) != 0)
-          if (arg_flags & ARGUMENT_REQUIRED) != 0
-            required_output << value
-          else
-            optional_output << value
-          end
-        end
+    # these are aliased (appear under several names)
+    ALIAS = ["crop"]
+
+    # turn a gtype into a ruby type name
+    def self.gtype_to_ruby gtype
+      fundamental = GObject.g_type_fundamental gtype
+      type_name = GObject.g_type_name gtype
+
+      if MAP_GO_TO_RUBY.include? type_name
+        type_name = MAP_GO_TO_RUBY[type_name]
       end
 
+      if fundamental == GObject::GFLAGS_TYPE ||
+          fundamental == GObject::GENUM_TYPE
+        type_name = "Vips::" + type_name[/Vips(.*)/, 1]
+      end
+
+      type_name
+    end
+
+    def self.generate_operation introspect
+      return if (introspect.flags & OPERATION_DEPRECATED) != 0
+      return if NO_GENERATE.include? introspect.name
+
+      method_args = introspect.method_args
+      required_output = introspect.required_output
+      optional_input = introspect.doc_optional_input
+      optional_output = introspect.doc_optional_output
+
       print "# @!method "
-      print "self." unless member_x
-      print "#{nickname}("
-      print required_input.map { |x| x[:name] }.join(", ")
-      print ", " if required_input.length > 0
+      print "self." unless introspect.member_x
+      print "#{introspect.name}("
+      print method_args.map { |x| x[:yard_name] }.join(", ")
+      print ", " if method_args.length > 0
       puts "**opts)"
 
-      puts "#   #{description.capitalize}."
+      puts "#   #{introspect.description.capitalize}."
 
-      required_input.each do |arg|
-        puts "#   @param #{arg[:name]} [#{arg[:type_name]}] #{arg[:blurb]}"
+      method_args.each do |details|
+        yard_name = details[:yard_name]
+        gtype = details[:gtype]
+        blurb = details[:blurb]
+
+        puts "#   @param #{yard_name} [#{gtype_to_ruby(gtype)}] #{blurb}"
       end
 
       puts "#   @param opts [Hash] Set of options"
-      optional_input.each do |arg|
-        puts "#   @option opts [#{arg[:type_name]}] :#{arg[:name]} " +
-             "#{arg[:blurb]}"
+      optional_input.each do |arg_name, details|
+        yard_name = details[:yard_name]
+        gtype = details[:gtype]
+        rtype = gtype_to_ruby gtype
+        blurb = details[:blurb]
+
+        puts "#   @option opts [#{rtype}] :#{yard_name} #{blurb}"
       end
-      optional_output.each do |arg|
-        print "#   @option opts [#{arg[:type_name]}] :#{arg[:name]}"
-        puts " Output #{arg[:blurb]}"
+      optional_output.each do |arg_name, details|
+        yard_name = details[:yard_name]
+        gtype = details[:gtype]
+        rtype = gtype_to_ruby gtype
+        blurb = details[:blurb]
+
+        puts "#   @option opts [#{rtype}] :#{yard_name} Output #{blurb}"
       end
 
       print "#   @return ["
       if required_output.length == 0
         print "nil"
       elsif required_output.length == 1
-        print required_output.first[:type_name]
+        print gtype_to_ruby(required_output.first[:gtype])
       else
         print "Array<"
-        print required_output.map { |x| x[:type_name] }.join(", ")
+        print required_output.map { |x| gtype_to_ruby(x[:gtype]) }.join(", ")
         print ">"
       end
       if optional_output.length > 0
@@ -1470,30 +1719,42 @@ module Vips
       puts ""
     end
 
-    generate_class = lambda do |gtype, _|
-      nickname = Vips::nickname_find gtype
+    def self.generate
+      alias_gtypes = {}
+      ALIAS.each do |name|
+        gtype = Vips.type_find "VipsOperation", name
+        alias_gtypes[gtype] = name
+      end
 
-      if nickname
-        begin
-          # can fail for abstract types
-          op = Vips::Operation.new nickname
-        rescue Vips::Error
-          nil
+      generate_class = lambda do |gtype, _|
+        name = if alias_gtypes.key? gtype
+          alias_gtypes[gtype]
+        else
+          Vips.nickname_find gtype
         end
 
-        generate_operation.(gtype, nickname, op) if op
-      end
+        if name
+          begin
+            # can fail for abstract types
+            introspect = Vips::Introspect.get_yard name
+          rescue Vips::Error
+            nil
+          end
 
-      Vips::vips_type_map gtype, generate_class, nil
-    end
+          generate_operation(introspect) if introspect
+        end
+
+        Vips.vips_type_map gtype, generate_class, nil
+      end
 
-    puts "module Vips"
-    puts "  class Image"
-    puts ""
+      puts "module Vips"
+      puts "  class Image"
+      puts ""
 
-    generate_class.(GObject::g_type_from_name("VipsOperation"), nil)
+      generate_class.call(GObject.g_type_from_name("VipsOperation"), nil)
 
-    puts "  end"
-    puts "end"
+      puts "  end"
+      puts "end"
+    end
   end
 end