ruby-vips 2.0.17 → 2.1.0

data/example/example2.rb

@@ -1,16 +1,16 @@
 #!/usr/bin/ruby
 
-require 'logger'
-require 'vips'
+require "logger"
+require "vips"
 
 puts ""
 puts "starting up:"
 
 # this makes vips keep a list of all active objects which we can print out
-Vips::leak_set true
+Vips.leak_set true
 
 # disable the operation cache
-Vips::cache_set_max 0
+Vips.cache_set_max 0
 
 # GLib::logger.level = Logger::DEBUG
 
@@ -20,7 +20,7 @@ n.times do |i|
   puts ""
   puts "call #{i} ..."
   out = Vips::Operation.call "black", [200, 300]
-  if out.width != 200 or out.height != 300
+  if out.width != 200 || out.height != 300
     puts "bad image result from black"
   end
 end
@@ -28,7 +28,7 @@ end
 puts ""
 puts "after #{n} calls:"
 GC.start
-Vips::Object::print_all
+Vips::Object.print_all
 
 puts ""
 puts "shutting down:"

data/example/example3.rb

@@ -1,19 +1,19 @@
 #!/usr/bin/ruby
 
-require 'vips'
+require "vips"
 
 # this makes vips keep a list of all active objects
-Vips::leak_set true
+Vips.leak_set true
 
 # disable the operation cache
 # Vips::cache_set_max 0
 
 # turn on debug logging
-GLib::logger.level = Logger::DEBUG
+GLib.logger.level = Logger::DEBUG
 
-1.times do |i|
+10.times do |i|
   puts "loop #{i} ..."
   im = Vips::Image.new_from_file ARGV[0]
-  im = im.embed 100, 100, 3000, 3000, :extend => :mirror
+  im = im.embed 100, 100, 3000, 3000, extend: :mirror
   im.write_to_file "x.v"
 end

data/example/example4.rb

@@ -1,9 +1,9 @@
 #!/usr/bin/ruby
 
-require 'vips'
+require "vips"
 
 # this makes vips keep a list of all active objects
-Vips::leak_set true
+Vips.leak_set true
 
 # disable the operation cache
 # Vips::cache_set_max 0

data/example/example5.rb

@@ -1,6 +1,6 @@
 #!/usr/bin/ruby
 
-require 'vips'
+require "vips"
 
 # this makes vips keep a list of all active objects
 # Vips::leak_set true
@@ -15,7 +15,7 @@ if ARGV.length < 2
   raise "usage: #{$PROGRAM_NAME}: input-file output-file"
 end
 
-im = Vips::Image.new_from_file ARGV[0], :access => :sequential
+im = Vips::Image.new_from_file ARGV[0], access: :sequential
 
 im *= [1, 2, 1]
 
@@ -23,8 +23,8 @@ im *= [1, 2, 1]
 # make it ourselves
 # if you are OK with scale=1, you can just pass the array directly to .conv()
 mask = Vips::Image.new_from_array [[-1, -1, -1],
-                                   [-1, 16, -1],
-                                   [-1, -1, -1]], 8
+  [-1, 16, -1],
+  [-1, -1, -1]], 8
 im = im.conv mask
 
 im.write_to_file ARGV[1]

data/example/inheritance_with_refcount.rb

@@ -1,7 +1,7 @@
 #!/usr/bin/ruby
 
-require 'ffi'
-require 'forwardable'
+require "ffi"
+require "forwardable"
 
 # this is really very crude logging
 
@@ -29,7 +29,7 @@ end
 
 module GLib
   extend FFI::Library
-  ffi_lib 'gobject-2.0'
+  ffi_lib "gobject-2.0"
 
   def self.set_log_domain(_domain)
     # FIXME: this needs hooking up
@@ -68,8 +68,8 @@ module GLib
       def self.included(base)
         base.class_eval do
           layout :g_type_instance, :pointer,
-                 :ref_count, :uint,
-                 :qdata, :pointer
+            :ref_count, :uint,
+            :qdata, :pointer
         end
       end
     end
@@ -85,7 +85,7 @@ module GLib
 
       def self.release(ptr)
         log "GLib::GObject::ManagedStruct.release: unreffing #{ptr}"
-        GLib::g_object_unref(ptr) unless ptr.null?
+        GLib.g_object_unref(ptr) unless ptr.null?
       end
     end
 
@@ -116,7 +116,7 @@ module GLib
 
     class << self
       def ffi_struct
-        self.const_get(:Struct)
+        const_get(:Struct)
       end
     end
 
@@ -127,7 +127,7 @@ module GLib
 
     class << self
       def ffi_managed_struct
-        self.const_get(:ManagedStruct)
+        const_get(:ManagedStruct)
       end
     end
   end
@@ -138,10 +138,10 @@ end
 
 module Vips
   extend FFI::Library
-  ffi_lib 'vips'
+  ffi_lib "vips"
 
   LOG_DOMAIN = "VIPS"
-  GLib::set_log_domain(LOG_DOMAIN)
+  GLib.set_log_domain(LOG_DOMAIN)
 
   # need to repeat this
   typedef :ulong, :GType
@@ -153,19 +153,19 @@ module Vips
   attach_function :vips_error_clear, [], :void
 
   def self.get_error
-    errstr = Vips::vips_error_buffer
-    Vips::vips_error_clear
+    errstr = Vips.vips_error_buffer
+    Vips.vips_error_clear
     errstr
   end
 
-  if Vips::vips_init($0) != 0
-    puts Vips::get_error
+  if Vips.vips_init($0) != 0
+    puts Vips.get_error
     exit 1
   end
 
-  at_exit {
-    Vips::vips_shutdown
-  }
+  at_exit do
+    Vips.vips_shutdown
+  end
 
   attach_function :vips_object_print_all, [], :void
   attach_function :vips_leak_set, [:int], :void
@@ -188,15 +188,15 @@ module Vips
         base.class_eval do
           # don't actually need most of these, remove them later
           layout :parent, GLib::GObject::Struct,
-             :constructed, :int,
-             :static_object, :int,
-             :argument_table, :pointer,
-             :nickname, :string,
-             :description, :string,
-             :preclose, :int,
-             :close, :int,
-             :postclose, :int,
-             :local_memory, :size_t
+            :constructed, :int,
+            :static_object, :int,
+            :argument_table, :pointer,
+            :nickname, :string,
+            :description, :string,
+            :preclose, :int,
+            :close, :int,
+            :postclose, :int,
+            :local_memory, :size_t
         end
       end
     end
@@ -250,7 +250,7 @@ module Vips
     end
 
     def self.new_partial
-      VipsImage.new(Vips::vips_image_new)
+      VipsImage.new(Vips.vips_image_new)
     end
   end
 
@@ -258,12 +258,11 @@ module Vips
 end
 
 puts "creating image"
-begin
-  x = Vips::VipsImage.new_partial
-  puts "x = #{x}"
-  puts ""
-  puts "x[:parent] = #{x[:parent]}"
-  puts ""
-  puts "x[:parent][:description] = #{x[:parent][:description]}"
-  puts ""
-end
+
+x = Vips::VipsImage.new_partial
+puts "x = #{x}"
+puts ""
+puts "x[:parent] = #{x[:parent]}"
+puts ""
+puts "x[:parent][:description] = #{x[:parent][:description]}"
+puts ""

data/example/progress.rb

@@ -1,6 +1,6 @@
 #!/usr/bin/ruby
 
-require 'vips'
+require "vips"
 
 image = Vips::Image.black 1, 100000
 image.set_progress true
@@ -12,11 +12,11 @@ def progress_to_s(name, progress)
   puts "    progress.tpels = #{progress[:tpels]}"
   puts "    progress.npels = #{progress[:npels]}"
   puts "    progress.percent = #{progress[:percent]}"
-end 
+end
 
 image.signal_connect :preeval do |progress|
   progress_to_s("preeval", progress)
-end 
+end
 
 image.signal_connect :eval do |progress|
   progress_to_s("eval", progress)

data/example/thumb.rb

@@ -1,25 +1,25 @@
-#!/usr/bin/env ruby
+#!/usr/bin/ruby
 
 # batch-process a lot of files
 #
 # this should run in constant memory -- if it doesn't, something has broken
 
-require 'vips'
+require "vips"
 
 # benchmark thumbnail via a memory buffer
 def via_memory(filename, thumbnail_width)
   data = IO.binread(filename)
 
-  thumb = Vips::Image.thumbnail_buffer data, thumbnail_width, crop: 'centre'
+  thumb = Vips::Image.thumbnail_buffer data, thumbnail_width, crop: "centre"
 
-  thumb.write_to_buffer '.jpg'
+  thumb.write_to_buffer ".jpg"
 end
 
 # benchmark thumbnail via files
 def via_files(filename, thumbnail_width)
-  thumb = Vips::Image.thumbnail filename, thumbnail_width, crop: 'centre'
+  thumb = Vips::Image.thumbnail filename, thumbnail_width, crop: "centre"
 
-  thumb.write_to_buffer '.jpg'
+  thumb.write_to_buffer ".jpg"
 end
 
 ARGV.each do |filename|

data/example/trim8.rb

@@ -7,7 +7,7 @@
 # non-zero row or column is the object edge. We make the mask image with an
 # amount-different-from-background image plus a threshold.
 
-require 'vips'
+require "vips"
 
 im = Vips::Image.new_from_file ARGV[0]
 

data/example/watermark.rb

@@ -1,11 +1,11 @@
 #!/usr/bin/ruby
 
-require 'vips'
+require "vips"
 
 im = Vips::Image.new_from_file ARGV[0], access: :sequential
 
 # make the text mask
-text = Vips::Image.text ARGV[2], width: 200, dpi: 200, font: 'sans bold'
+text = Vips::Image.text ARGV[2], width: 200, dpi: 200, font: "sans bold"
 text = text.rotate(-45)
 # make the text transparent
 text = (text * 0.3).cast(:uchar)

data/example/wobble.rb

@@ -1,6 +1,6 @@
 #!/usr/bin/ruby
 
-require 'vips'
+require "vips"
 
 image = Vips::Image.new_from_file ARGV[0]
 

data/lib/ruby-vips.rb

@@ -1 +1 @@
-require 'vips'
+require "vips"

data/lib/vips.rb

@@ -4,8 +4,8 @@
 # Author::    John Cupitt  (mailto:jcupitt@gmail.com)
 # License::   MIT
 
-require 'ffi'
-require 'logger'
+require "ffi"
+require "logger"
 
 # This module uses FFI to make a simple layer over the glib and gobject
 # libraries.
@@ -37,12 +37,12 @@ module GLib
   class << self
     attr_accessor :logger
   end
-  @logger = Logger.new(STDOUT)
+  @logger = Logger.new($stdout)
   @logger.level = Logger::WARN
 
   extend FFI::Library
 
-  ffi_lib library_name('glib-2.0', 0)
+  ffi_lib library_name("glib-2.0", 0)
 
   attach_function :g_malloc, [:size_t], :pointer
 
@@ -52,20 +52,20 @@ module GLib
 
   callback :g_log_func, [:string, :int, :string, :pointer], :void
   attach_function :g_log_set_handler,
-      [:string, :int, :g_log_func, :pointer], :int
+    [:string, :int, :g_log_func, :pointer], :int
   attach_function :g_log_remove_handler, [:string, :int], :void
 
   # log flags
-  LOG_FLAG_RECURSION          = 1 << 0
-  LOG_FLAG_FATAL              = 1 << 1
+  LOG_FLAG_RECURSION = 1 << 0
+  LOG_FLAG_FATAL = 1 << 1
 
   # GLib log levels
-  LOG_LEVEL_ERROR             = 1 << 2 # always fatal
-  LOG_LEVEL_CRITICAL          = 1 << 3
-  LOG_LEVEL_WARNING           = 1 << 4
-  LOG_LEVEL_MESSAGE           = 1 << 5
-  LOG_LEVEL_INFO              = 1 << 6
-  LOG_LEVEL_DEBUG             = 1 << 7
+  LOG_LEVEL_ERROR = 1 << 2 # always fatal
+  LOG_LEVEL_CRITICAL = 1 << 3
+  LOG_LEVEL_WARNING = 1 << 4
+  LOG_LEVEL_MESSAGE = 1 << 5
+  LOG_LEVEL_INFO = 1 << 6
+  LOG_LEVEL_DEBUG = 1 << 7
 
   # map glib levels to Logger::Severity
   GLIB_TO_SEVERITY = {
@@ -83,9 +83,9 @@ module GLib
   @glib_log_handler_id = 0
 
   # module-level, so it's not GCd away
-  LOG_HANDLER = Proc.new do |domain, level, message, _user_data|
+  LOG_HANDLER = proc { |domain, level, message, _user_data|
     @logger.log(GLIB_TO_SEVERITY[level], message, domain)
-  end
+  }
 
   def self.remove_log_handler
     if @glib_log_handler_id != 0 && @glib_log_domain
@@ -95,7 +95,7 @@ module GLib
   end
 
   def self.set_log_domain domain
-    GLib::remove_log_handler
+    GLib.remove_log_handler
 
     @glib_log_domain = domain
 
@@ -125,7 +125,7 @@ module GLib
       # on shutdown and we don't want LOG_HANDLER to be invoked
       # after Ruby has gone
       at_exit {
-        GLib::remove_log_handler
+        GLib.remove_log_handler
       }
     end
   end
@@ -134,7 +134,7 @@ end
 module GObject
   extend FFI::Library
 
-  ffi_lib library_name('gobject-2.0', 0)
+  ffi_lib library_name("gobject-2.0", 0)
 
   # we can't just use ulong, windows has different int sizing rules
   if FFI::Platform::ADDRESS_SIZE == 64
@@ -162,8 +162,8 @@ module GObject
   GOBJECT_TYPE = g_type_from_name "GObject"
 end
 
-require 'vips/gobject'
-require 'vips/gvalue'
+require "vips/gobject"
+require "vips/gvalue"
 
 # This module provides a binding for the [libvips image processing
 # library](https://libvips.github.io/libvips/).
@@ -208,12 +208,10 @@ require 'vips/gvalue'
 # for full details
 # on the various modes available.
 #
-# You can also load formatted images from
-# memory buffers, create images that wrap C-style memory arrays, or make images
-# from constants.
-#
-# Use {Source} and {Image.new_from_source} to load images from any data
-# source, for example URIs.
+# You can also load formatted images from memory buffers, create images that
+# wrap C-style memory arrays, or make images from constants. Use {Source}
+# and {Image.new_from_source} to load images from any data source, for
+# example URIs.
 #
 # The next line:
 #
@@ -256,7 +254,7 @@ require 'vips/gvalue'
 # suffix. You can also write formatted images to memory buffers, or dump
 # image data to a raw memory array.
 #
-# Use {Target} and {Image#write_to_target} to write formatted images to 
+# Use {Target} and {Image#write_to_target} to write formatted images to
 # any data sink, for example URIs.
 #
 # # How it works
@@ -409,36 +407,83 @@ require 'vips/gvalue'
 #
 # # Automatic YARD documentation
 #
-# The bulk of these API docs are generated automatically by
-# {Vips::Yard::generate}. It examines
-# libvips and writes a summary of each operation and the arguments and options
-# that that operation expects.
+# The bulk of these API docs are generated automatically by {Yard#generate}.
+# It examines libvips and writes a summary of each operation and the arguments
+# and options that that operation expects.
 #
-# Use the [C API
-# docs](https://libvips.github.io/libvips/API/current)
+# Use the [C API # docs](https://libvips.github.io/libvips/API/current)
 # for more detail.
 #
 # # Enums
 #
 # The libvips enums, such as `VipsBandFormat` appear in ruby-vips as Symbols
 # like `:uchar`. They are documented as a set of classes for convenience, see
-# the class list.
+# {Vips::BandFormat}, for example.
 #
 # # Draw operations
 #
-# Paint operations like {Image#draw_circle} and {Image#draw_line}
-# modify their input image. This
-# makes them hard to use with the rest of libvips: you need to be very careful
-# about the order in which operations execute or you can get nasty crashes.
+# There are two ways of calling the libvips draw operations, like
+# {Image#draw_circle} and {Image#draw_line}.
+#
+# First, you can use them like functions. For example:
+#
+# ```ruby
+# y = x.draw_line 255, 0, 0, x.width, x.height
+# ```
+#
+# This will make a new image, `y`, which is a copy of `x` but with a line
+# drawn across it. `x` is unchanged.
+#
+# This is simple, but will be slow if you want to draw many lines, since
+# ruby-vips will make a copy of the whole image each time.
+#
+# You can use {Image#mutate} to make a {MutableImage}. This is an image which
+# is unshared and is only available inside the {Image#mutate} block. Within
+# this block, you can use `!` versions of the draw operations to modify images
+# and avoid the copy. For example:
+#
+# ```ruby
+# image = image.mutate do |mutable|
+#   (0 ... 1).step(0.01) do |i|
+#     mutable.draw_line! 255, mutable.width * i, 0, 0, mutable.height * (1 - i)
+#   end
+# end
+# ```
+#
+# Now each {Image#draw_line} will directly modify the mutable image, saving
+# the copy. This is much faster and needs much less memory.
+#
+# # Metadata read
 #
-# The wrapper spots operations of this type and makes a private copy of the
-# image in memory before calling the operation. This stops crashes, but it does
-# make it inefficient. If you draw 100 lines on an image, for example, you'll
-# copy the image 100 times. The wrapper does make sure that memory is recycled
-# where possible, so you won't have 100 copies in memory.
+# Use {Image#get_fields} to get a list of the metadata fields that an image
+# supports. ICC profiles, for example, are in a field called
+# `icc-profile-data`. Use `vipsheader -a something.jpg` at the command-line
+# to see all the fields on an image.
 #
-# If you want to avoid the copies, you'll need to call drawing operations
-# yourself.
+# Use {Image#get_typeof} to get the type of a field. Types are integers, with
+# 0 meaning "no such field". Constants like {GObject::GINT_TYPE} are useful for
+# testing field types.
+#
+# You can read image metadata using {Image#get}. The field value is converted
+# to a Ruby value in the obvious way.
+#
+# # Metadata write
+#
+# You can also set and remove image metadata fields. Images are immutable, so
+# you must make any changes inside a {Image#mutate} block. For example:
+#
+# ```ruby
+# image = image.mutate do |mutable|
+#   image.get_fields.each do |field|
+#     mutable.remove! field unless field == "icc-profile-data"
+#   end
+# end
+# ```
+#
+# To remove all metadata except the icc profile.
+#
+# You can use {MutableImage#set!} to change the value of an existing field,
+# and {MutableImage#set_type!} to create a new field with a specified type.
 #
 # # Progress
 #
@@ -448,7 +493,7 @@ require 'vips/gvalue'
 # ```ruby
 # image = Vips::Image.black 1, 100000
 # image.set_progress true
-# 
+#
 # def progress_to_s(name, progress)
 #   puts "#{name}:"
 #   puts "    run = #{progress[:run]}"
@@ -457,23 +502,23 @@ require 'vips/gvalue'
 #   puts "    npels = #{progress[:npels]}"
 #   puts "    percent = #{progress[:percent]}"
 # end
-# 
+#
 # image.signal_connect :preeval do |progress|
 #   progress_to_s("preeval", progress)
 # end
-# 
+#
 # image.signal_connect :eval do |progress|
 #   progress_to_s("eval", progress)
 #   image.set_kill(true) if progress[:percent] > 50
 # end
-# 
+#
 # image.signal_connect :posteval do |progress|
 #   progress_to_s("posteval", progress)
 # end
-# 
+#
 # image.avg
 # ```
-# 
+#
 # The `:eval` signal will fire for every tile that is processed. You can stop
 # progress with {Image#set_kill} and processing will end with an exception.
 #
@@ -525,10 +570,10 @@ require 'vips/gvalue'
 module Vips
   extend FFI::Library
 
-  ffi_lib library_name('vips', 42)
+  ffi_lib library_name("vips", 42)
 
   LOG_DOMAIN = "VIPS"
-  GLib::set_log_domain LOG_DOMAIN
+  GLib.set_log_domain LOG_DOMAIN
 
   typedef :ulong, :GType
 
@@ -542,9 +587,9 @@ module Vips
     def initialize msg = nil
       if msg
         @details = msg
-      elsif Vips::vips_error_buffer != ""
-        @details = Vips::vips_error_buffer
-        Vips::vips_error_clear
+      elsif Vips.vips_error_buffer != ""
+        @details = Vips.vips_error_buffer
+        Vips.vips_error_clear
       else
         @details = nil
       end
@@ -554,7 +599,7 @@ module Vips
     #
     # @return [String] The error message
     def to_s
-      if @details != nil
+      if !@details.nil?
         @details
       else
         super.to_s
@@ -564,8 +609,8 @@ module Vips
 
   attach_function :vips_init, [:string], :int
 
-  if Vips::vips_init($0) != 0
-    throw Vips::get_error
+  if Vips.vips_init($0) != 0
+    throw Vips.get_error
   end
 
   # don't use at_exit to call vips_shutdown, it causes problems with fork, and
@@ -629,7 +674,7 @@ module Vips
   # Don't use this, instead change GLib::logger.level.
   def self.set_debug debug
     if debug
-      GLib::logger.level = Logger::DEBUG
+      GLib.logger.level = Logger::DEBUG
     end
   end
 
@@ -651,36 +696,37 @@ module Vips
     # vips_foreign_get_suffixes() was added in libvips 8.8
     return [] unless Vips.respond_to? :vips_foreign_get_suffixes
 
-    array = Vips::vips_foreign_get_suffixes
+    array = Vips.vips_foreign_get_suffixes
 
     names = []
     p = array
     until (q = p.read_pointer).null?
       suff = q.read_string
-      GLib::g_free q
+      GLib.g_free q
       names << suff unless names.include? suff
       p += FFI::Type::POINTER.size
     end
-    GLib::g_free array
+    GLib.g_free array
 
     names
   end
 
-  LIBRARY_VERSION = Vips::version_string
+  LIBRARY_VERSION = Vips.version_string
 
   # libvips has this arbitrary number as a sanity-check upper bound on image
   # size. It's sometimes useful to know when calculating scale factors.
   MAX_COORD = 10000000
 end
 
-require 'vips/object'
-require 'vips/operation'
-require 'vips/image'
-require 'vips/interpolate'
-require 'vips/region'
-require 'vips/version'
-require 'vips/connection'
-require 'vips/source'
-require 'vips/sourcecustom'
-require 'vips/target'
-require 'vips/targetcustom'
+require "vips/object"
+require "vips/operation"
+require "vips/image"
+require "vips/mutableimage"
+require "vips/interpolate"
+require "vips/region"
+require "vips/version"
+require "vips/connection"
+require "vips/source"
+require "vips/sourcecustom"
+require "vips/target"
+require "vips/targetcustom"