Class: Vips::MutableImage

Inherits:
Object show all
Extended by:
Forwardable
Defined in:
lib/vips/mutableimage.rb

Overview

This class represents a libvips image which can be modified. See Image#mutate.

Defined Under Namespace

Modules: MutableImageLayout Classes: ManagedStruct, Struct

Instance Attribute Summary collapse

Attributes inherited from GObject::GObject

#ptr, #references

Instance Method Summary collapse

Methods inherited from Object

#get, #get_pspec, #get_typeof, #get_typeof_error, print_all, #set, #signal_connect

Methods inherited from GObject::GObject

#ffi_managed_struct, ffi_managed_struct, ffi_struct, #ffi_struct

Constructor Details

#initialize(image) ⇒ MutableImage

Make a Vips::MutableImage from a regular Image.

This is for internal use only. See Image#mutate for the user-facing interface.



50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
 
# File 'lib/vips/mutableimage.rb', line 50

def initialize(image)
  # We take a copy of the regular Image to ensure we have an unshared
  # (unique) object. We forward things like #width and #height to this, and
  # it's the thing we return at the end of the mutate block.
  copy_image = image.copy

  # Use ptr since we need the raw unwrapped pointer inside the image ...
  # and make the ref that gobject will unref when it finishes.
  # See also the comment on set_type! before changing this.
  pointer = copy_image.ptr
  ::GObject.g_object_ref pointer
  super(pointer)

  # and save the copy ready for when we finish mutating
  @image = copy_image
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(name, *args, **options) ⇒ Object

Invoke a vips operation with Operation#call, using self as the first input argument. Operation#call will only allow operations that modify self when passed a Vips::MutableImage.

Parameters:

  • name (String) —

    vips operation to call

Returns:

  • result of vips operation



95
96
97
 
# File 'lib/vips/mutableimage.rb', line 95

def method_missing name, *args, **options
  Vips::Operation.call name.to_s, [self, *args], options
end

Instance Attribute Details

#image ⇒ Object (readonly)

Get the Image this Vips::MutableImage is modifying. Only use this once you have finished all modifications.

This is for internal use only. See Image#mutate for the user-facing interface.



44
45
46
 
# File 'lib/vips/mutableimage.rb', line 44

def image
  @image
end

Instance Method Details

#draw_point!(ink, left, top, **opts) ⇒ Object

Draw a point on an image.

See Image#draw_rect.



102
103
104
 
# File 'lib/vips/mutableimage.rb', line 102

def draw_point! ink, left, top, **opts
  draw_rect! ink, left, top, 1, 1, **opts
end

#inspect ⇒ Object 



67
68
69
 
# File 'lib/vips/mutableimage.rb', line 67

def inspect
  "#<MutableImage #{width}x#{height} #{format}, #{bands} bands, #{interpretation}>"
end

#remove!(name) ⇒ Object

Remove a metadata item from an image.

For example:

x.remove! "icc-profile-data"

Parameters:

  • name (String) —

    Metadata field to remove



172
173
174
175
176
177
178
 
# File 'lib/vips/mutableimage.rb', line 172

def remove! name
  # See set_type! for an explanation. Image#remove can't throw an
  # exception, so there's no need to ensure we unref.
  ::GObject.g_object_unref ptr
  Vips.vips_image_remove self, name
  ::GObject.g_object_ref ptr
end

#respond_to?(name, include_all = false) ⇒ Boolean

Returns:

  • (Boolean) 


71
72
73
74
75
76
77
78
79
80
 
# File 'lib/vips/mutableimage.rb', line 71

def respond_to? name, include_all = false
  # To support keyword args, we need to tell Ruby that final image
  # arguments cannot be hashes of keywords.
  #
  # https://makandracards.com/makandra/
  #   36013-heads-up-ruby-implicitly-converts-a-hash-to-keyword-arguments
  return false if name == :to_hash

  super
end

#respond_to_missing?(name, include_all = false) ⇒ Boolean

Returns:

  • (Boolean) 


82
83
84
85
86
87
 
# File 'lib/vips/mutableimage.rb', line 82

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

  super
end

#set!(name, value) ⇒ Object

Set the value of a metadata item on an image. The metadata item must already exist. Ruby types are automatically transformed into the matching GObject::GValue, if possible.

For example, you can use this to set an image's ICC profile:

x.set! "icc-profile-data", profile

where profile is an ICC profile held as a binary string object.

Parameters:

  • name (String) —

    Metadata field to set

  • value (Object) —

    Value to set

See Also:



159
160
161
 
# File 'lib/vips/mutableimage.rb', line 159

def set! name, value
  set_type! get_typeof(name), name, value
end

#set_type!(gtype, name, value) ⇒ Object

Create a metadata item on an image of the specifed type. Ruby types are automatically transformed into the matching glib type (eg. GObject::GINT_TYPE), if possible.

For example, you can use this to set an image's ICC profile:

x.set_type! Vips::BLOB_TYPE, "icc-profile-data", profile

where profile is an ICC profile held as a binary string object.

Parameters:

  • gtype (Integer) —

    GType of item

  • name (String) —

    Metadata field to set

  • value (Object) —

    Value to set

See Also:



122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
 
# File 'lib/vips/mutableimage.rb', line 122

def set_type! gtype, name, value
  gvalue = GObject::GValue.alloc
  gvalue.init gtype
  gvalue.set value

  # libvips 8.9.1 had a terrible misfeature which would block metadata
  # modification unless the object had a ref_count of 1. MutableImage
  # will always have a ref_count of at least 2 (the parent gobject keeps a
  # ref, and we keep a ref to the copy ready to return to our caller),
  # so we must temporarily drop the refs to 1 around metadata changes.
  #
  # See https://github.com/libvips/ruby-vips/issues/291
  begin
    ::GObject.g_object_unref ptr
    Vips.vips_image_set self, name, gvalue
  ensure
    ::GObject.g_object_ref ptr
  end

  gvalue.unset
end