class Vips::Image

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

Public Class Methods

matrix_from_array(width, height, array) click to toggle source
# File lib/vips/image.rb, line 345
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
  Vips::Image.new image
end
method_missing(name, *args, **options) click to toggle source

Invoke a vips operation with {Vips::Operation.call}.

# File lib/vips/image.rb, line 215
def self.method_missing name, *args, **options
  Vips::Operation.call name.to_s, args, options
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::Image.new_from_array [1, 2, 3] “`

or

“‘ image = Vips::Image.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/vips/image.rb, line 379
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
  unless 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
    unless array.all? { |x| x.is_a? Array }
      raise Vips::Error, "Not a 2D array."
    end
    unless array.all? { |x| x.length == width }
      raise Vips::Error, "Array not rectangular."
    end

    array = array.flatten
  else
    height = 1
    width = array.length
  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

  # 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
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 binary string. Load options may be passed as strings or appended as a hash. For example:

“‘ image = Vips::Image.new_from_buffer memory_buffer, “shrink=2” “`

or alternatively:

“‘ image = Vips::Image.new_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. Not all loaders support load from buffer, but at least JPEG, PNG and TIFF images will work.

Loading is fast: only enough of the image is loaded to be able to fill out the header. Pixels will only be decompressed 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/vips/image.rb, line 299
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?

  Vips::Operation.call loader, [data], opts, option_string
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::Image.new_from_filefred.jpg” “`

You can also supply options as a hash, for example:

“‘ image = Vips::Image.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 for the JPEG loader.

Loading is fast: only enough of the image is loaded to be able to fill out the header. Pixels will only be decompressed when they are needed.

@!macro [new] vips.loadopts

@param opts [Hash] 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/vips/image.rb, line 255
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

  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
new_from_source(source, option_string, **opts) click to toggle source

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

# File lib/vips/image.rb, line 338
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
respond_to?(name, include_all = false) click to toggle source
Calls superclass method
# File lib/vips/image.rb, line 198
def self.respond_to? name, include_all = false
  # respond to all vips operations by nickname
  return true if Vips::type_find("VipsOperation", name.to_s) != 0

  super
end

Private Class Methods

complex?(format) click to toggle source
# File lib/vips/image.rb, line 102
def self.complex? format
  format_number = GObject::GValue.from_nick BAND_FORMAT_TYPE, format
  Vips::vips_band_format_iscomplex(format_number) != 0
end
float?(format) click to toggle source
# File lib/vips/image.rb, line 107
def self.float? format
  format_number = GObject::GValue.from_nick BAND_FORMAT_TYPE, format
  Vips::vips_band_format_isfloat(format_number) != 0
end
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/vips/image.rb, line 115
def self.run_cmplx image, &block
  original_format = image.format

  unless Image::complex? image.format
    if image.bands % 2 != 0
      raise Vips::Error, "not an even number of bands"
    end

    unless Image::float? 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)

  unless Image::complex? 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/vips/image.rb, line 98
def self.smap x, &block
  x.is_a?(Array) ? x.map { |y| smap(y, &block) } : block.(x)
end

Public Instance Methods

!() click to toggle source

Equivalent to image ^ -1

@return [Image] image with bits flipped

# File lib/vips/image.rb, line 957
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/vips/image.rb, line 1031
def != other
  # for equality, we must allow tests against nil
  if other == nil
    true
  else
    call_enum "relational", 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/vips/image.rb, line 901
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/vips/image.rb, line 942
def & other
  call_enum "boolean", 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/vips/image.rb, line 883
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/vips/image.rb, line 910
def ** other
  call_enum "math2", 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/vips/image.rb, line 865
def + other
  other.is_a?(Vips::Image) ?
      add(other) : linear(1, other)
end
+@() click to toggle source

@return [Image] image

# File lib/vips/image.rb, line 969
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/vips/image.rb, line 874
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/vips/image.rb, line 976
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/vips/image.rb, line 892
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/vips/image.rb, line 984
def < other
  call_enum "relational", 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/vips/image.rb, line 918
def << other
  call_enum "boolean", 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/vips/image.rb, line 993
def <= other
  call_enum "relational", 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/vips/image.rb, line 1018
def == other
  # for equality, we must allow tests against nil
  if other == nil
    false
  else
    call_enum "relational", 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/vips/image.rb, line 1001
def > other
  call_enum "relational", 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/vips/image.rb, line 1010
def >= other
  call_enum "relational", 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/vips/image.rb, line 926
def >> other
  call_enum "boolean", 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/vips/image.rb, line 1044
def [] index
  if index.is_a? Range
    n = index.size
    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/vips/image.rb, line 950
def ^ other
  call_enum "boolean", 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/vips/image.rb, line 1301
def acos
  math :acos
end
add_alpha() click to toggle source

Append an alpha channel to an image.

@return [Image] new image

# File lib/vips/image.rb, line 831
def add_alpha
  ptr = GenericPtr.new
  result = Vips::vips_addalpha self, ptr
  raise Vips::Error if result != 0

  Vips::Image.new ptr[:value]
end
asin() click to toggle source

Return the inverse sine of an image in degrees.

@return [Image] inverse sine of each pixel

# File lib/vips/image.rb, line 1294
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/vips/image.rb, line 1308
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/vips/image.rb, line 1113
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/vips/image.rb, line 1127
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/vips/image.rb, line 1142
def bandjoin other
  unless other.is_a? Array
    other = [other]
  end

  # if other is just Numeric, we can use bandjoin_const
  not_all_real = !other.all? { |x| x.is_a? Numeric }

  if not_all_real
    Vips::Image.bandjoin([self] + other)
  else
    bandjoin_const other
  end
end
bandor() click to toggle source

OR the bands of an image together

@return [Image] all bands ORed together

# File lib/vips/image.rb, line 1120
def bandor
  bandbool :or
end
bands() click to toggle source

Get number of image bands.

@return [Integer] number of image bands

# File lib/vips/image.rb, line 732
def bands
  get "bands"
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/vips/image.rb, line 1134
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/vips/image.rb, line 1099
def ceil
  round :ceil
end
coding() click to toggle source

Get image coding.

@return [Symbol] image coding

# File lib/vips/image.rb, line 753
def coding
  get "coding"
end
composite(overlay, mode, **opts) click to toggle source

Composite a set of images with a set of blend modes.

@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 [Boolean] :premultiplied Images have premultiplied alpha @return [Image] blended image

# File lib/vips/image.rb, line 1165
def composite overlay, mode, **opts
  unless overlay.is_a? Array
    overlay = [overlay]
  end
  unless mode.is_a? Array
    mode = [mode]
  end

  mode = mode.map do |x|
    GObject::GValue.from_nick Vips::BLEND_MODE_TYPE, x
  end

  Vips::Image.composite([self] + overlay, mode, **opts)
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/vips/image.rb, line 1258
def conj
  Image::run_cmplx(self) { |x| x.complex :conj }
end
copy_memory() click to toggle source

Copy an image to a memory area.

This can be useful for reusing results, but can obviously use a lot of memory for large images. See {Image#tilecache} for a way of caching parts of an image.

@return [Image] new memory image

# File lib/vips/image.rb, line 847
def copy_memory
  new_image = Vips::vips_image_copy_memory self
  Vips::Image.new new_image
end
cos() click to toggle source

Return the cosine of an image in degrees.

@return [Image] cosine of each pixel

# File lib/vips/image.rb, line 1280
def cos
  math :cos
end
cross_phase(other) click to toggle source

Calculate the cross phase of two images.

@param other [Image, Real, Array<Real>] cross phase with this @return [Image] cross phase

# File lib/vips/image.rb, line 1266
def cross_phase other
  complex2 other, :cross_phase
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/vips/image.rb, line 1374
def dilate mask
  morph mask, :dilate
end
draw_point(ink, left, top, **opts) click to toggle source

Draw a point on an image.

See {Image#draw_rect}.

@return [Image] modified image

# File lib/vips/image.rb, line 857
def draw_point ink, left, top, **opts
  draw_rect ink, left, top, 1, 1, opts
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/vips/image.rb, line 1362
def erode mask
  morph mask, :erode
end
exp() click to toggle source

Return e ** pixel.

@return [Image] e ** pixel

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

Return 10 ** pixel.

@return [Image] 10 ** pixel

# File lib/vips/image.rb, line 1336
def exp10
  math :exp10
end
filename() click to toggle source

Get image filename, if any.

@return [String] image filename

# File lib/vips/image.rb, line 760
def filename
  get "filename"
end
fliphor() click to toggle source

Flip horizontally.

@return [Image] image flipped horizontally

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

Flip vertically.

@return [Image] image flipped vertically

# File lib/vips/image.rb, line 1350
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/vips/image.rb, line 1092
def floor
  round :floor
end
format() click to toggle source

Get image format.

@return [Symbol] image format

# File lib/vips/image.rb, line 739
def format
  get "format"
end
get(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 “icc-profile-data” “`

and profile will be an array containing the profile.

@param name [String] Metadata field to get @return [Object] Value of field

Calls superclass method Vips::Object#get
# File lib/vips/image.rb, line 619
def get name
  # with old libvips, we must fetch properties (as opposed to
  # metadata) via VipsObject
  unless Vips::at_least_libvips?(8, 5)
    return super if parent_get_typeof(name) != 0
  end

  gvalue = GObject::GValue.alloc
  raise Vips::Error if Vips::vips_image_get(self, name, gvalue) != 0
  result = gvalue.get
  gvalue.unset

  result
end
get_fields() click to toggle source

Get the names of all fields on an image. Use this to loop over all image metadata.

@return [[String]] array of field names

# File lib/vips/image.rb, line 638
def get_fields
  # 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

  names = []
  p = array
  until (q = p.read_pointer).null?
    names << q.read_string
    GLib::g_free q
    p += FFI::Type::POINTER.size
  end
  GLib::g_free array

  names
end
get_typeof(name) click to toggle source

Get the ‘GType` of a metadata field. The result is 0 if no such field exists.

@see get @param name [String] Metadata field to fetch @return [Integer] GType

# File lib/vips/image.rb, line 595
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)
    gtype = parent_get_typeof name
    return gtype if gtype != 0
  end

  Vips::vips_image_get_typeof self, name
end
Also aliased as: parent_get_typeof
get_value(name) click to toggle source

compatibility: old name for get

# File lib/vips/image.rb, line 706
def get_value name
  get name
end
has_alpha?() click to toggle source

Detect if image has an alpha channel

@return [Boolean] true if image has an alpha channel.

# File lib/vips/image.rb, line 821
def has_alpha?
  return Vips::vips_image_hasalpha(self) != 0
end
height() click to toggle source

Get image height, in pixels.

@return [Integer] image height, in pixels

# File lib/vips/image.rb, line 725
def height
  get "height"
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 opts [Hash] set of options @option opts [Boolean] :blend (false) Blend smoothly between th and el @return [Image] merged image

# File lib/vips/image.rb, line 1408
def ifthenelse(th, el, **opts)
  match_image = [th, el, self].find { |x| x.is_a? Vips::Image }

  unless th.is_a? Vips::Image
    th = Operation.imageize match_image, th
  end
  unless el.is_a? Vips::Image
    el = Operation.imageize match_image, el
  end

  Vips::Operation.call "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/vips/image.rb, line 1220
def imag
  complexget :imag
end
inspect() click to toggle source
# File lib/vips/image.rb, line 180
def inspect
  "#<Image #{width}x#{height} #{format}, #{bands} bands, #{interpretation}>"
end
interpretation() click to toggle source

Get image interpretation.

@return [Symbol] image interpretation

# File lib/vips/image.rb, line 746
def interpretation
  get "interpretation"
end
log() click to toggle source

Return the natural log of an image.

@return [Image] natural log of each pixel

# File lib/vips/image.rb, line 1315
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/vips/image.rb, line 1322
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/vips/image.rb, line 1184
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/vips/image.rb, line 1206
def median size = 3
  rank size, size, (size * size) / 2
end
method_missing(name, *args, **options) click to toggle source

Invoke a vips operation with {Vips::Operation.call}, using self as the first input argument.

@param name [String] vips operation to call @return result of vips operation

# File lib/vips/image.rb, line 210
def method_missing name, *args, **options
  Vips::Operation.call name.to_s, [self, *args], options
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/vips/image.rb, line 1195
def minpos
  v, opts = min x: true, y: true
  x = opts['x']
  y = opts['y']
  return v, x, y
end
new_from_image(value) click to toggle source

A new image is created with the same width, height, format, interpretation, resolution and offset as self, but with every pixel set to the specified value.

You can pass an array to make a many-band image, or a single value to make a one-band image.

@param value [Real, Array<Real>] value to put in each pixel @return [Image] constant image

# File lib/vips/image.rb, line 425
def new_from_image value
  pixel = (Vips::Image.black(1, 1) + value).cast(format)
  image = pixel.embed 0, 0, width, height, extend: :copy
  image.copy interpretation: interpretation, xres: xres, yres: yres,
    xoffset: xoffset, yoffset: yoffset
end
offset() click to toggle source

Get offset metadata.

@return [Float] image offset

# File lib/vips/image.rb, line 804
def offset
  return 0 if get_typeof("offset") == 0

  get "offset"
end
parent_get_typeof(name)
Alias for: get_typeof
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/vips/image.rb, line 1233
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/vips/image.rb, line 1213
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/vips/image.rb, line 1246
def rect
  Image::run_cmplx(self) { |x| x.complex :rect }
end
remove(name) click to toggle source

Remove a metadata item from an image.

@param name [String] Metadata field to remove

# File lib/vips/image.rb, line 701
def remove name
  Vips::vips_image_remove self, name
end
respond_to?(name, include_all = false) click to toggle source
Calls superclass method
# File lib/vips/image.rb, line 184
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

  # respond to all vips operations by nickname
  return true if Vips::type_find("VipsOperation", name.to_s) != 0

  super
end
rint() click to toggle source

Return the nearest integral value.

@return [Image] rint of image

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

Rotate by 180 degrees clockwise.

@return [Image] rotated image

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

Rotate by 270 degrees clockwise.

@return [Image] rotated image

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

Rotate by 90 degrees clockwise.

@return [Image] rotated image

# File lib/vips/image.rb, line 1381
def rot90
  rot :d90
end
scale() click to toggle source

Get scale metadata.

@return [Float] image scale

# File lib/vips/image.rb, line 795
def scale
  return 1 if get_typeof("scale") == 0

  get "scale"
end
scaleimage(**opts) click to toggle source

Scale an image to uchar. This is the vips ‘scale` operation, but renamed to avoid a clash with the `.scale` property.

@param opts [Hash] Set of options @return [Vips::Image] Output image

# File lib/vips/image.rb, line 1426
def scaleimage **opts
  Vips::Image.scale self, **opts
end
set(name, value) click to toggle source

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.

@see set_type @param name [String] Metadata field to set @param value [Object] Value to set

# File lib/vips/image.rb, line 694
def set name, value
  set_type get_typeof(name), name, value
end
set_kill(kill) click to toggle source

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

# File lib/vips/image.rb, line 585
def set_kill kill
  Vips::vips_image_set_kill self, kill
end
set_progress(state) click to toggle source

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

# File lib/vips/image.rb, line 574
def set_progress state
  Vips::vips_image_set_progress self, state
end
set_type(gtype, name, value) click to toggle source

Create a metadata item on an image of the specifed type. Ruby types are automatically transformed into the matching ‘GType`, if possible.

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

“‘ x = y.set_type Vips::BLOB_TYPE, “icc-profile-data”, profile “`

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

@see set @param gtype [Integer] GType of item @param name [String] Metadata field to set @param value [Object] Value to set

# File lib/vips/image.rb, line 671
def set_type gtype, name, value
  gvalue = GObject::GValue.alloc
  gvalue.init gtype
  gvalue.set value
  Vips::vips_image_set self, name, gvalue
  gvalue.unset
end
set_value(name, value) click to toggle source

compatibility: old name for set

# File lib/vips/image.rb, line 711
def set_value name, value
  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/vips/image.rb, line 1273
def sin
  math :sin
end
size() click to toggle source

Get the image size.

@return [Integer, Integer] image width and height

# File lib/vips/image.rb, line 813
def size
  [width, height]
end
tan() click to toggle source

Return the tangent of an image in degrees.

@return [Image] tangent of each pixel

# File lib/vips/image.rb, line 1287
def tan
  math :tan
end
to_a() click to toggle source

Convert to an Array. This will be slow for large images.

@return [Array] array of Fixnum

# File lib/vips/image.rb, line 1058
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

  # 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] + '*'

  # and unpack into something like [1, 2, 3, 4 ..]
  array = memory.unpack(template)

  # gather band elements together
  pixel_array = array.each_slice(bands).to_a

  # build rows
  row_array = pixel_array.each_slice(width).to_a

  return row_array
end
width() click to toggle source

Get image width, in pixels.

@return [Integer] image width, in pixels

# File lib/vips/image.rb, line 718
def width
  get "width"
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 for JPEG save.

@param format_string [String] save format plus options @macro vips.saveopts @return [String] the image saved in the specified format

# File lib/vips/image.rb, line 499
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 buffer saver for '#{filename}'."
  end

  buffer = Vips::Operation.call saver, [self], opts, option_string
  raise Vips::Error if buffer == nil

  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 for JPEG save.

@!macro [new] vips.saveopts

@param opts [Hash] 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/vips/image.rb, line 461
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

  Vips::Operation.call saver, [self, filename], opts, option_string

  write_gc
end
write_to_memory() click to toggle source

Write this image to a large memory buffer.

@return [String] the pixels as a huge binary string

# File lib/vips/image.rb, line 556
def write_to_memory
  len = Vips::SizeStruct.new
  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]
end
write_to_target(target, format_string, **opts) click to toggle source

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” “`

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

# File lib/vips/image.rb, line 541
def write_to_target target, 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_target filename
  if saver == nil
    raise Vips::Error, "No known target saver for '#{filename}'."
  end

  Vips::Operation.call saver, [self, target], opts, option_string
  write_gc
end
xoffset() click to toggle source

Get image xoffset.

@return [Integer] image xoffset

# File lib/vips/image.rb, line 767
def xoffset
  get "xoffset"
end
xres() click to toggle source

Get image x resolution.

@return [Float] image x resolution

# File lib/vips/image.rb, line 781
def xres
  get "xres"
end
yoffset() click to toggle source

Get image yoffset.

@return [Integer] image yoffset

# File lib/vips/image.rb, line 774
def yoffset
  get "yoffset"
end
yres() click to toggle source

Get image y resolution.

@return [Float] image y resolution

# File lib/vips/image.rb, line 788
def yres
  get "yres"
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/vips/image.rb, line 934
def | other
  call_enum "boolean", other, :or
end
~() click to toggle source

Equivalent to image ^ -1

@return [Image] image with bits flipped

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

Private Instance Methods

call_enum(name, other, enum) click to toggle source

handy for expanding enum operations

# File lib/vips/image.rb, line 142
def call_enum(name, other, enum)
  if other.is_a?(Vips::Image)
    Vips::Operation.call name.to_s, [self, other, enum]
  else
    Vips::Operation.call name.to_s + "_const", [self, enum, other]
  end
end
write_gc() click to toggle source
# File lib/vips/image.rb, line 166
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