class Vips::Image

This class represents a libvips image. See the {Vips} module documentation for an introduction to using this module.

Public Class Methods

method_missing(name, *args) click to toggle source

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
new_from_array(array, scale = 1, offset = 0) click to toggle source

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
new_from_buffer(data, option_string, opts = {}) click to toggle source

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
new_from_file(name, opts = {}) click to toggle source

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_cmplx(image, &block) click to toggle source

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
smap(x, &block) click to toggle source

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

!() click to toggle source

Equivalent to image ^ -1

@return [Image] image with bits flipped

# File lib/vips8/image.rb, line 825
def !
    self ^ -1
end
!=(other) click to toggle source

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
%(other) click to toggle source

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
&(other) click to toggle source

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
*(other) click to toggle source

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
**(other) click to toggle source

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
+(other) click to toggle source

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
+@() click to toggle source

@return [Image] image

# File lib/vips8/image.rb, line 837
def +@
    self
end
-(other) click to toggle source

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
-@() click to toggle source

Equivalent to image * -1

@return [Image] negative of image

# File lib/vips8/image.rb, line 844
def -@
    self * -1
end
/(other) click to toggle source

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
<(other) click to toggle source

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
<<(other) click to toggle source

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
<=(other) click to toggle source

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
==(other) click to toggle source

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
>(other) click to toggle source

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
>=(other) click to toggle source

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
>>(other) click to toggle source

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
[](index) click to toggle source

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
^(other) click to toggle source

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
acos() click to toggle source

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
asin() click to toggle source

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
atan() click to toggle source

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
bandand() click to toggle source

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
bandeor() click to toggle source

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
bandjoin(other) click to toggle source

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
bandor() click to toggle source

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
bandsplit() click to toggle source

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
ceil() click to toggle source

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
conj() click to toggle source

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
cos() click to toggle source

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(mask) click to toggle source

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(mask) click to toggle source

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
exp() click to toggle source

Return e ** pixel.

@return [Image] e ** pixel

# File lib/vips8/image.rb, line 1146
def exp
    math :exp
end
exp10() click to toggle source

Return 10 ** pixel.

@return [Image] 10 ** pixel

# File lib/vips8/image.rb, line 1153
def exp10
    math :exp10
end
fliphor() click to toggle source

Flip horizontally.

@return [Image] image flipped horizontally

# File lib/vips8/image.rb, line 1160
def fliphor
    flip :horizontal
end
flipver() click to toggle source

Flip vertically.

@return [Image] image flipped vertically

# File lib/vips8/image.rb, line 1167
def flipver
    flip :vertical
end
floor() click to toggle source

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_value(name) click to toggle source

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
getpoint(x, y) click to toggle source

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
ifthenelse(th, el, opts = {}) click to toggle source

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
imag() click to toggle source

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
log() click to toggle source

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
log10() click to toggle source

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
maxpos() click to toggle source

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
median(size = 3) click to toggle source

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
method_missing(name, *args) click to toggle source

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
minpos() click to toggle source

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
polar() click to toggle source

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
real() click to toggle source

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
rect() click to toggle source

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
rint() click to toggle source

Return the nearest integral value.

@return [Image] rint of image

# File lib/vips8/image.rb, line 947
def rint
    round :rint
end
rot180() click to toggle source

Rotate by 180 degrees clockwise.

@return [Image] rotated image

# File lib/vips8/image.rb, line 1205
def rot180
    rot :d180
end
rot270() click to toggle source

Rotate by 270 degrees clockwise.

@return [Image] rotated image

# File lib/vips8/image.rb, line 1212
def rot270
    rot :d270
end
rot90() click to toggle source

Rotate by 90 degrees clockwise.

@return [Image] rotated image

# File lib/vips8/image.rb, line 1198
def rot90
    rot :d90
end
set_value(name, value) click to toggle source

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
sin() click to toggle source

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
tan() click to toggle source

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_to_buffer(format_string, opts = {}) click to toggle source

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_to_file(name, opts = {}) click to toggle source

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
|(other) click to toggle source

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
~() click to toggle source

Equivalent to image ^ -1

@return [Image] image with bits flipped

# File lib/vips8/image.rb, line 832
def ~
    self ^ -1
end

Private Instance Methods

write_gc() click to toggle source
# 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