class Vips::Image
This class represents a libvips image. See the {Vips} module documentation for an introduction to using this module.
Public Class Methods
Invoke a vips operation with {call}.
# File lib/vips8/image.rb, line 379 def self.method_missing(name, *args) Vips::call_base name.to_s, nil, "", args end
Create a new Image
from a 1D or 2D array. A 1D array becomes an image with height 1. Use ‘scale` and `offset` to set the scale and offset fields in the header. These are useful for integer convolutions.
For example:
“‘ image = Vips::new_from_array [1, 2, 3] “`
or
“‘ image = Vips::new_from_array [
[-1, -1, -1], [-1, 16, -1], [-1, -1, -1]], 8
“‘
for a simple sharpening mask.
@param array [Array] the pixel data as an array of numbers @param scale [Real] the convolution scale @param offset [Real] the convolution offset @return [Image] the image
# File lib/vips8/image.rb, line 499 def self.new_from_array(array, scale = 1, offset = 0) # we accept a 1D array and assume height == 1, or a 2D array # and check all lines are the same length if not array.is_a? Array raise Vips::Error, "Argument is not an array." end if array[0].is_a? Array height = array.length width = array[0].length if not array.all? {|x| x.is_a? Array} raise Vips::Error, "Not a 2D array." end if not array.all? {|x| x.length == width} raise Vips::Error, "Array not rectangular." end array = array.flatten else height = 1 width = array.length end if not 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 if image == nil raise Vips::Error end # be careful to set them as double image.set_double 'scale', scale.to_f image.set_double 'offset', offset.to_f return image end
Create a new {Image} for an image encoded in a format, such as JPEG, in a memory string. Load options may be passed encoded as strings, or appended as a hash. For example:
“‘ image = Vips::new_from_from_buffer memory_buffer, “shrink=2” “`
or alternatively:
“‘ image = Vips::new_from_from_buffer memory_buffer, “”, :shrink => 2 “`
The options available depend on the file format. Try something like:
“‘ $ vips jpegload_buffer “`
at the command-line to see the available options. Only JPEG, PNG and TIFF images can be read from memory buffers.
Loading is fast: only enough of the image is loaded to be able to fill out the header. Pixels will only be processed when they are needed.
@param data [String] the data to load from @param option_string [String] load options as a string @macro vips.loadopts @return [Image] the loaded image
# File lib/vips8/image.rb, line 464 def self.new_from_buffer(data, option_string, opts = {}) loader = Vips::Foreign.find_load_buffer data if loader == nil raise Vips::Error end Vips::call_base loader, nil, option_string, [data, opts] end
Return a new {Image} for a file on disc. This method can load images in any format supported by vips. The filename can include load options, for example:
“‘ image = Vips::new_from_file “fred.jpg” “`
You can also supply options as a hash, for example:
“‘ image = Vips::new_from_file “fred.jpg”, :shrink => 2 “`
The full set of options available depend upon the load operation that will be executed. Try something like:
“‘ $ vips jpegload “`
at the command-line to see a summary of the available options.
Loading is fast: only enough of the image is loaded to be able to fill out the header. Pixels will only be processed when they are needed.
@!macro [new] vips.loadopts
@param [Hash] opts set of options @option opts [Boolean] :disc (true) Open large images via a temporary disc file @option opts [Vips::Access] :access (:random) Access mode for file
@param name [String] the filename to load from @macro vips.loadopts @return [Image] the loaded image
# File lib/vips8/image.rb, line 418 def self.new_from_file(name, opts = {}) # very common, and Vips::filename_get_filename will segv if we pass # this if name == nil raise Error, "filename is nil" end filename = Vips::filename_get_filename name option_string = Vips::filename_get_options name loader = Vips::Foreign.find_load filename if loader == nil raise Vips::Error end Vips::call_base loader, nil, option_string, [filename, opts] end
Private Class Methods
run a complex operation on a complex image, or an image with an even number of bands … handy for things like running .polar on .index images
# File lib/vips8/image.rb, line 311 def self.run_cmplx(image, &block) original_format = image.format if not Vips::band_format_iscomplex image.format if image.bands % 2 != 0 raise Error, "not an even number of bands" end if not Vips::band_format_isfloat image.format image = image.cast :float end new_format = image.format == :double ? :dpcomplex : :complex image = image.copy :format => new_format, :bands => image.bands / 2 end image = block.(image) if not Vips::band_format_iscomplex original_format new_format = image.format == :dpcomplex ? :double : :float image = image.copy :format => new_format, :bands => image.bands * 2 end image end
handy for overloads … want to be able to apply a function to an array or to a scalar
# File lib/vips8/image.rb, line 304 def self.smap(x, &block) x.is_a?(Array) ? x.map {|x| smap(x, &block)} : block.(x) end
Public Instance Methods
Equivalent to image ^ -1
@return [Image] image with bits flipped
# File lib/vips8/image.rb, line 825 def ! self ^ -1 end
Compare inequality to nil, an image, constant or array.
@param other [nil, Image
, Real, Array<Real>] test inequality to this @return [Image] result of inequality
# File lib/vips8/image.rb, line 904 def !=(other) if other == nil true elsif other.is_a?(Vips::Image) relational(other, :noteq) else relational_const(other, :noteq) end end
Remainder after integer division with an image, constant or array.
@param other [Image, Real, Array<Real>] self modulo this @return [Image] result of modulo
# File lib/vips8/image.rb, line 763 def %(other) other.is_a?(Vips::Image) ? remainder(other) : remainder_const(other) end
Integer bitwise AND with an image, constant or array.
@param other [Image, Real, Array<Real>] bitwise AND with this @return [Image] result of bitwise AND
# File lib/vips8/image.rb, line 808 def &(other) other.is_a?(Vips::Image) ? boolean(other, :and) : boolean_const(other, :and) end
Multiply an image, constant or array.
@param other [Image, Real, Array<Real>] Thing to multiply by self @return [Image] result of multiplication
# File lib/vips8/image.rb, line 746 def *(other) other.is_a?(Vips::Image) ? multiply(other) : linear(other, 0) end
Raise to power of an image, constant or array.
@param other [Image, Real, Array<Real>] self to the power of this @return [Image] result of power
# File lib/vips8/image.rb, line 772 def **(other) other.is_a?(Vips::Image) ? math2(other, :pow) : math2_const(other, :pow) end
Add an image, constant or array.
@param other [Image, Real, Array<Real>] Thing to add to self @return [Image] result of addition
# File lib/vips8/image.rb, line 729 def +(other) other.is_a?(Vips::Image) ? add(other) : linear(1, other) end
@return [Image] image
# File lib/vips8/image.rb, line 837 def +@ self end
Subtract an image, constant or array.
@param other [Image, Real, Array<Real>] Thing to subtract from self @return [Image] result of subtraction
# File lib/vips8/image.rb, line 737 def -(other) other.is_a?(Vips::Image) ? subtract(other) : linear(1, Image::smap(other) {|x| x * -1}) end
Equivalent to image * -1
@return [Image] negative of image
# File lib/vips8/image.rb, line 844 def -@ self * -1 end
Divide an image, constant or array.
@param other [Image, Real, Array<Real>] Thing to divide self by @return [Image] result of division
# File lib/vips8/image.rb, line 754 def /(other) other.is_a?(Vips::Image) ? divide(other) : linear(Image::smap(other) {|x| 1.0 / x}, 0) end
Relational less than with an image, constant or array.
@param other [Image, Real, Array<Real>] relational less than with this @return [Image] result of less than
# File lib/vips8/image.rb, line 852 def <(other) other.is_a?(Vips::Image) ? relational(other, :less) : relational_const(other, :less) end
Integer left shift with an image, constant or array.
@param other [Image, Real, Array<Real>] shift left by this much @return [Image] result of left shift
# File lib/vips8/image.rb, line 781 def <<(other) other.is_a?(Vips::Image) ? boolean(other, :lshift) : boolean_const(other, :lshift) end
Relational less than or equal to with an image, constant or array.
@param other [Image, Real, Array<Real>] relational less than or
equal to with this
@return [Image] result of less than or equal to
# File lib/vips8/image.rb, line 862 def <=(other) other.is_a?(Vips::Image) ? relational(other, :lesseq) : relational_const(other, :lesseq) end
Compare equality to nil, an image, constant or array.
@param other [nil, Image
, Real, Array<Real>] test equality to this @return [Image] result of equality
# File lib/vips8/image.rb, line 890 def ==(other) if other == nil false elsif other.is_a?(Vips::Image) relational(other, :equal) else relational_const(other, :equal) end end
Relational more than with an image, constant or array.
@param other [Image, Real, Array<Real>] relational more than with this @return [Image] result of more than
# File lib/vips8/image.rb, line 871 def >(other) other.is_a?(Vips::Image) ? relational(other, :more) : relational_const(other, :more) end
Relational more than or equal to with an image, constant or array.
@param other [Image, Real, Array<Real>] relational more than or
equal to with this
@return [Image] result of more than or equal to
# File lib/vips8/image.rb, line 881 def >=(other) other.is_a?(Vips::Image) ? relational(other, :moreeq) : relational_const(other, :moreeq) end
Integer right shift with an image, constant or array.
@param other [Image, Real, Array<Real>] shift right by this much @return [Image] result of right shift
# File lib/vips8/image.rb, line 790 def >>(other) other.is_a?(Vips::Image) ? boolean(other, :rshift) : boolean_const(other, :rshift) end
Fetch bands using a number or a range
@param index [Numeric, Range] extract these band(s) @return [Image] extracted band(s)
# File lib/vips8/image.rb, line 918 def [](index) if index.is_a? Range n = index.end - index.begin n += 1 if not index.exclude_end? extract_band index.begin, :n => n elsif index.is_a? Numeric extract_band index else raise Vips::Error, "[] index is not range or numeric." end end
Integer bitwise EOR with an image, constant or array.
@param other [Image, Real, Array<Real>] bitwise EOR with this @return [Image] result of bitwise EOR
# File lib/vips8/image.rb, line 817 def ^(other) other.is_a?(Vips::Image) ? boolean(other, :eor) : boolean_const(other, :eor) end
Return the inverse cosine of an image in degrees.
@return [Image] inverse cosine of each pixel
# File lib/vips8/image.rb, line 1118 def acos math :acos end
Return the inverse sine of an image in degrees.
@return [Image] inverse sine of each pixel
# File lib/vips8/image.rb, line 1111 def asin math :asin end
Return the inverse tangent of an image in degrees.
@return [Image] inverse tangent of each pixel
# File lib/vips8/image.rb, line 1125 def atan math :atan end
AND the bands of an image together
@return [Image] all bands ANDed together
# File lib/vips8/image.rb, line 954 def bandand bandbool :and end
EOR the bands of an image together
@return [Image] all bands EORed together
# File lib/vips8/image.rb, line 968 def bandeor bandbool :eor end
Join a set of images bandwise.
@param other [Image, Array<Image>, Real, Array<Real>] bands to append @return [Image] many band image
# File lib/vips8/image.rb, line 983 def bandjoin(other) if not other.is_a? Array other = [other] end Vips::Image.bandjoin([self] + other) end
OR the bands of an image together
@return [Image] all bands ORed together
# File lib/vips8/image.rb, line 961 def bandor bandbool :or end
Split an n-band image into n separate images.
@return [Array<Image>] Array of n one-band images
# File lib/vips8/image.rb, line 975 def bandsplit (0...bands).map {|i| extract_band(i)} end
Return the smallest integral value not less than the argument.
@return [Image] ceil of image
# File lib/vips8/image.rb, line 940 def ceil round :ceil end
Return the complex conjugate of an image.
The image can be complex, in which case the return image will also be complex, or must have an even number of bands, in which case pairs of bands are treated as (x, y) coordinates.
@return [Image] complex conjugate
# File lib/vips8/image.rb, line 1083 def conj Image::run_cmplx(self) {|x| x.complex :conj} end
Return the cosine of an image in degrees.
@return [Image] cosine of each pixel
# File lib/vips8/image.rb, line 1097 def cos math :cos end
Dilate with a structuring element.
The structuring element must be an array with 0 for black, 255 for white and 128 for don’t care.
@param mask [Image, Array<Real>, Array<Array<Real>>] structuring
element
@return [Image] dilated image
# File lib/vips8/image.rb, line 1191 def dilate(mask) morph mask, :dilate end
Erode with a structuring element.
The structuring element must be an array with 0 for black, 255 for white and 128 for don’t care.
@param mask [Image, Array<Real>, Array<Array<Real>>] structuring
element
@return [Image] eroded image
# File lib/vips8/image.rb, line 1179 def erode(mask) morph mask, :erode end
Return e ** pixel.
@return [Image] e ** pixel
# File lib/vips8/image.rb, line 1146 def exp math :exp end
Return 10 ** pixel.
@return [Image] 10 ** pixel
# File lib/vips8/image.rb, line 1153 def exp10 math :exp10 end
Flip horizontally.
@return [Image] image flipped horizontally
# File lib/vips8/image.rb, line 1160 def fliphor flip :horizontal end
Flip vertically.
@return [Image] image flipped vertically
# File lib/vips8/image.rb, line 1167 def flipver flip :vertical end
Return the largest integral value not greater than the argument.
@return [Image] floor of image
# File lib/vips8/image.rb, line 933 def floor round :floor end
Get a metadata item from an image. Ruby types are constructed automatically from the ‘GValue`, if possible.
For example, you can read the ICC profile from an image like this:
“‘ profile = image.get_value “icc-profile-data” “`
and profile will be an array containing the profile.
@see get @param name [String] Metadata field to set @return [Object] Value of field
# File lib/vips8/image.rb, line 676 def get_value(name) ret, gval = get name if ret[0] != 0 raise Vips::Error, "Field #{name} not found." end value = gval.value Argument::unwrap(value) end
get the value of a pixel as an array
@param x [Integer] x coordinate to sample @param y [Integer] y coordinate to sample @return [Array<Float>] the pixel values as an array
# File lib/vips8/image.rb, line 1018 def getpoint(x, y) # vips has an operation that does this, but we can't call it via # gobject-introspection 3.0.7 since it's missing array double # get # # remove this def when gobject-introspection updates crop(x, y, 1, 1).bandsplit.map {|i| i.avg} end
Select pixels from ‘th` if `self` is non-zero and from `el` if `self` is zero. Use the `:blend` option to fade smoothly between `th` and `el`.
@param th [Image, Real, Array<Real>] true values @param el [Image, Real, Array<Real>] false values @param [Hash] opts set of options @option opts [Boolean] :blend (false) Blend smoothly between th and el @return [Image] merged image
# File lib/vips8/image.rb, line 1225 def ifthenelse(th, el, opts = {}) match_image = [th, el, self].find {|x| x.is_a? Vips::Image} if not th.is_a? Vips::Image th = Argument::imageize match_image, th end if not el.is_a? Vips::Image el = Argument::imageize match_image, el end Vips::call_base "ifthenelse", self, "", [th, el, opts] end
Return the imaginary part of a complex image.
@return [Image] imaginary part of complex image
# File lib/vips8/image.rb, line 1045 def imag complexget :imag end
Return the natural log of an image.
@return [Image] natural log of each pixel
# File lib/vips8/image.rb, line 1132 def log math :log end
Return the log base 10 of an image.
@return [Image] base 10 log of each pixel
# File lib/vips8/image.rb, line 1139 def log10 math :log10 end
Return the coordinates of the image maximum.
@return [Real, Real, Real] maximum value, x coordinate of maximum, y
coordinate of maximum
# File lib/vips8/image.rb, line 995 def maxpos v, opts = max :x => true, :y => true x = opts['x'] y = opts['y'] return v, x, y end
a median filter
@param size [Integer] size of filter window @return [Image] result of median filter
# File lib/vips8/image.rb, line 1031 def median(size = 3) rank(size, size, (size * size) / 2) end
Invoke a vips operation with {call}, using self as the first input image argument.
@param name [String] vips operation to call @return result of vips operation
# File lib/vips8/image.rb, line 374 def method_missing(name, *args) Vips::call_base(name.to_s, self, "", args) end
Return the coordinates of the image minimum.
@return [Real, Real, Real] minimum value, x coordinate of minimum, y
coordinate of minimum
# File lib/vips8/image.rb, line 1006 def minpos v, opts = min :x => true, :y => true x = opts['x'] y = opts['y'] return v, x, y end
Return an image with rectangular pixels converted to polar.
The image can be complex, in which case the return image will also be complex, or must have an even number of bands, in which case pairs of bands are treated as (x, y) coordinates.
@see xyz @return [Image] image converted to polar coordinates
# File lib/vips8/image.rb, line 1058 def polar Image::run_cmplx(self) {|x| x.complex :polar} end
Return the real part of a complex image.
@return [Image] real part of complex image
# File lib/vips8/image.rb, line 1038 def real complexget :real end
Return an image with polar pixels converted to rectangular.
The image can be complex, in which case the return image will also be complex, or must have an even number of bands, in which case pairs of bands are treated as (x, y) coordinates.
@see xyz @return [Image] image converted to rectangular coordinates
# File lib/vips8/image.rb, line 1071 def rect Image::run_cmplx(self) {|x| x.complex :rect} end
Return the nearest integral value.
@return [Image] rint of image
# File lib/vips8/image.rb, line 947 def rint round :rint end
Rotate by 180 degrees clockwise.
@return [Image] rotated image
# File lib/vips8/image.rb, line 1205 def rot180 rot :d180 end
Rotate by 270 degrees clockwise.
@return [Image] rotated image
# File lib/vips8/image.rb, line 1212 def rot270 rot :d270 end
Rotate by 90 degrees clockwise.
@return [Image] rotated image
# File lib/vips8/image.rb, line 1198 def rot90 rot :d90 end
Set a metadata item on an image. 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_value “icc-profile-data”, profile “`
where ‘profile` is an ICC profile held as a binary string object.
@see set @param name [String] Metadata field to set @param value [Object] Value to set
# File lib/vips8/image.rb, line 700 def set_value(name, value) gtype = get_typeof name if gtype != 0 # array-ize value = Argument::arrayize gtype, value # blob-ize if gtype.type_is_a? GLib::Type["VipsBlob"] if not value.is_a? Vips::Blob value = Vips::Blob.copy value end end # image-ize if gtype.type_is_a? GLib::Type["VipsImage"] if not value.is_a? Vips::Image value = imageize match_image, value end end end set name, value end
Return the sine of an image in degrees.
@return [Image] sine of each pixel
# File lib/vips8/image.rb, line 1090 def sin math :sin end
Return the tangent of an image in degrees.
@return [Image] tangent of each pixel
# File lib/vips8/image.rb, line 1104 def tan math :tan end
Write this image to a memory buffer. Save options may be encoded in the format_string or given as a hash. For example:
“‘ buffer = image.write_to_buffer “.jpg” “`
or equivalently:
“‘ image.write_to_buffer “.jpg”, :Q => 90 “`
The full set of save options depend on the selected saver. Try something like:
“‘ $ vips jpegsave “`
to see all the available options.
@param format_string [String] save format plus options @macro vips.saveopts @return [String] the image saved in the specified format
# File lib/vips8/image.rb, line 604 def write_to_buffer(format_string, opts = {}) filename = Vips::filename_get_filename format_string option_string = Vips::filename_get_options format_string saver = Vips::Foreign.find_save_buffer filename if saver == nil raise Vips::Error, "No known saver for '#{filename}'." end buffer = Vips::call_base saver, self, option_string, [opts] write_gc return buffer end
Write this image to a file. Save options may be encoded in the filename or given as a hash. For example:
“‘ image.write_to_file “fred.jpg” “`
or equivalently:
“‘ image.write_to_file “fred.jpg”, :Q => 90 “`
The full set of save options depend on the selected saver. Try something like:
“‘ $ vips jpegsave “`
to see all the available options.
@!macro [new] vips.saveopts
@param [Hash] opts set of options @option opts [Boolean] :strip (false) Strip all metadata from image @option opts [Array<Float>] :background (0) Background colour to flatten alpha against, if necessary
@param name [String] filename to write to
# File lib/vips8/image.rb, line 566 def write_to_file(name, opts = {}) filename = Vips::filename_get_filename name option_string = Vips::filename_get_options name saver = Vips::Foreign.find_save filename if saver == nil raise Vips::Error, "No known saver for '#{filename}'." end Vips::call_base saver, self, option_string, [filename, opts] write_gc end
Integer bitwise OR with an image, constant or array.
@param other [Image, Real, Array<Real>] bitwise OR with this @return [Image] result of bitwise OR
# File lib/vips8/image.rb, line 799 def |(other) other.is_a?(Vips::Image) ? boolean(other, :or) : boolean_const(other, :or) end
Equivalent to image ^ -1
@return [Image] image with bits flipped
# File lib/vips8/image.rb, line 832 def ~ self ^ -1 end
Private Instance Methods
# File lib/vips8/image.rb, line 355 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