In Files

Parent

Included Modules

Files

GD2::Image

Introduction

Image is the abstract base class for Image::IndexedColor and Image::TrueColor.

Creating and Importing

Image objects are created either as a blank array of pixels:

image = Image::IndexedColor.new(width, height)
image = Image::TrueColor.new(width, height)

or by loading image data from a file or a string containing one of the supported image formats:

image = Image.load(file)
image = Image.load(string)

or by importing image data from a file given by its pathname:

image = Image.import(filename)

Exporting

After manipulating an image, it can be exported to a string in one of the supported image formats:

image.jpeg(quality = nil)
image.png(level = nil)
image.gif
image.wbmp(fgcolor)
image.gd
image.gd2(fmt = FMT_COMPRESSED)

or to a file in a format determined by the filename extension:

image.export(filename, options = {})

Attributes

palette[R]

The Palette object for this image

Public Class Methods

[](w, h) click to toggle source
Alias for: new
import(filename, options = {}) click to toggle source

Import an image from a file with the given filename. The :format option or the file extension is used to determine the image type (jpeg, png, gif, wbmp, gd, gd2, xbm, or xpm). The resulting image will be either of class Image::TrueColor or Image::IndexedColor.

If the file format is gd2, it is optionally possible to extract only a part of the image. Use options :x, :y, :width, and :height to specify the part of the image to import.

# File lib/gd2/image.rb, line 155
def self.import(filename, options = {})
  unless format = options.delete(:format)
    md = filename.match /\.([^.]+)\z/
    format = md ? md[1].downcase : nil
  end
  format = format.to_sym if format

  if format == :xpm
    raise ArgumentError, "Unexpected options #{options.inspect}" unless
      options.empty?
    ptr = SYM[:gdImageCreateFromXpm].call(filename)[0]
  elsif format == :gd2 && !options.empty?
    x, y, width, height =
      options.delete(:x) || 0, options.delete(:y) || 0,
      options.delete(:width)  || options.delete(:w),
      options.delete(:height) || options.delete(:h)
    raise ArgumentError, "Unexpected options #{options.inspect}" unless
      options.empty?
    raise ArgumentError, 'Missing required option :width' if width.nil?
    raise ArgumentError, 'Missing required option :height' if height.nil?
    ptr = File.open(filename, 'rb') do |file|
      SYM[:gdImageCreateFromGd2Part].call(file, x, y, width, height)[0]
    end
  else
    raise ArgumentError, "Unexpected options #{options.inspect}" unless
      options.empty?
    create_sym = {
      :jpeg => :gdImageCreateFromJpeg,
      :jpg  => :gdImageCreateFromJpeg,
      :png  => :gdImageCreateFromPng,
      :gif  => :gdImageCreateFromGif,
      :wbmp => :gdImageCreateFromWBMP,
      :gd   => :gdImageCreateFromGd,
      :gd2  => :gdImageCreateFromGd2,
      :xbm  => :gdImageCreateFromXbm
    }[format]
    raise UnrecognizedImageTypeError,
      'Format (or file extension) is not recognized' unless create_sym
    ptr = File.open(filename, 'rb') { |file| SYM[create_sym].call(file)[0] }
  end
  raise LibraryError unless ptr

  init_image_ptr(ptr)

  image = (image_true_color?(ptr) ?
    TrueColor : IndexedColor).allocate.init_with_image(ptr)

  block_given? ? yield(image) : image
end
load(src) click to toggle source

Load an image from a file or a string. The image type is detected automatically (JPEG, PNG, GIF, WBMP, or GD2). The resulting image will be either of class Image::TrueColor or Image::IndexedColor.

# File lib/gd2/image.rb, line 90
def self.load(src)
  case src
  when File
    pos = src.pos
    magic = src.read(4)
    src.pos = pos
    create = {
      :jpeg => :gdImageCreateFromJpeg,
      :png  => :gdImageCreateFromPng,
      :gif  => :gdImageCreateFromGif,
      :wbmp => :gdImageCreateFromWBMP,
      :gd2  => :gdImageCreateFromGd2
    }
    args = [src.to_ptr]
  when String
    magic = src
    create = {
      :jpeg => :gdImageCreateFromJpegPtr,
      :png  => :gdImageCreateFromPngPtr,
      :gif  => :gdImageCreateFromGifPtr,
      :wbmp => :gdImageCreateFromWBMPPtr,
      :gd2  => :gdImageCreateFromGd2Ptr
    }
    args = [src.length, src]
  else
    raise TypeError, 'Unexpected argument type'
  end

  type = data_type(magic) or
    raise UnrecognizedImageTypeError, 'Image data format is not recognized'
  ptr = SYM[create[type]].call(*args)[0]
  raise LibraryError unless ptr

  init_image_ptr(ptr)

  image = (image_true_color?(ptr) ?
    TrueColor : IndexedColor).allocate.init_with_image(ptr)

  block_given? ? yield(image) : image
end
new(w, h) click to toggle source

Create a new image of the specified dimensions. The default image class is Image::TrueColor; call this method on Image::IndexedColor instead if a palette image is desired.

# File lib/gd2/image.rb, line 76
def self.new(w, h)
  image = (self == Image) ?
    TrueColor.new(w, h) : allocate.init_with_size(w, h)

  block_given? ? yield(image) : image
end
Also aliased as: []

Public Instance Methods

==(other) click to toggle source

Compare this image with another image. Returns false if the images are not identical.

# File lib/gd2/image.rb, line 270
def ==(other)
  (compare(other) & CMP_IMAGE).zero?
end
[](x, y) click to toggle source

Return the color of the pixel at image location (x, y).

# File lib/gd2/image.rb, line 316
def [](x, y)
  pixel2color(get_pixel(x, y))
end
[]=(x, y, color) click to toggle source

Set the color of the pixel at image location (x, y).

# File lib/gd2/image.rb, line 321
def []=(x, y, color)
  set_pixel(x, y, color2pixel(color))
end
alpha_blending=(bool) click to toggle source

Set whether colors should be alpha blended with existing colors when pixels are modified. Alpha blending is not available for IndexedColor images.

# File lib/gd2/image.rb, line 372
def alpha_blending=(bool)
  SYM[:gdImageAlphaBlending].call(image_ptr, bool ? 1 : 0)
end
alpha_blending?() click to toggle source

Return true if colors will be alpha blended into the image when pixels are modified. Returns false if colors will be copied verbatim into the image without alpha blending when pixels are modified.

# File lib/gd2/image.rb, line 365
def alpha_blending?
  not image_ptr[:alphaBlendingFlag].zero?
end
aspect() click to toggle source

Return the aspect ratio of this image, as a floating point ratio of the width to the height.

# File lib/gd2/image.rb, line 299
def aspect
  width.to_f / height
end
clipping() click to toggle source

Return the current clipping rectangle. Use Image#with_clipping to temporarily modify the clipping rectangle.

# File lib/gd2/image.rb, line 403
def clipping
  r, rs = SYM[:gdImageGetClip].call(image_ptr, 0, 0, 0, 0)
  rs[1, 4]
end
clips?(x, y) click to toggle source

Return true if the current clipping rectangle excludes the given point.

# File lib/gd2/image.rb, line 424
def clips?(x, y)
  SYM[:gdImageBoundsSafe].call(image_ptr, x, y)[0].zero?
end
color2pixel(color) click to toggle source

Return a pixel value for the given color object.

# File lib/gd2/image.rb, line 346
def color2pixel(color)
  color.rgba
end
compare(other) click to toggle source

Compare this image with another image. Returns 0 if the images are identical, otherwise a bit field indicating the differences. See the GD2::CMP_* constants for individual bit flags.

# File lib/gd2/image.rb, line 264
def compare(other)
  SYM[:gdImageCompare].call(image_ptr, other.image_ptr)[0]
end
copy_from(other, dst_x, dst_y, src_x, src_y, dst_w, dst_h, src_w = nil, src_h = nil) click to toggle source

Copy a portion of another image to this image. If src_w and src_h are specified, the indicated portion of the source image will be resized (and resampled) to fit the indicated dimensions of the destination.

# File lib/gd2/image.rb, line 548
def copy_from(other, dst_x, dst_y, src_x, src_y,
    dst_w, dst_h, src_w = nil, src_h = nil)
  raise ArgumentError unless src_w.nil? == src_h.nil?
  if src_w
    SYM[:gdImageCopyResampled].call(image_ptr, other.image_ptr,
      dst_x, dst_y, src_x, src_y, dst_w, dst_h, src_w, src_h)
  else
    SYM[:gdImageCopy].call(image_ptr, other.image_ptr,
      dst_x, dst_y, src_x, src_y, dst_w, dst_h)
  end
  self
end
copy_from_rotated(other, dst_x, dst_y, src_x, src_y, w, h, angle) click to toggle source

Copy a portion of another image to this image, rotating the source portion first by the indicated angle (in radians). The dst_x and dst_y arguments indicate the center of the desired destination, and may be floating point.

# File lib/gd2/image.rb, line 565
def copy_from_rotated(other, dst_x, dst_y, src_x, src_y, w, h, angle)
  SYM[:gdImageCopyRotated].call(image_ptr, other.image_ptr,
    dst_x.to_f, dst_y.to_f, src_x, src_y, w, h, angle.to_degrees.round)
  self
end
crop(x, y, w, h) click to toggle source

Like Image#crop! except a new image is returned.

# File lib/gd2/image.rb, line 604
def crop(x, y, w, h)
  clone.crop!(x, y, w, h)
end
crop!(x, y, w, h) click to toggle source

Crop this image to the specified dimensions, such that (x, y) becomes (0, 0).

# File lib/gd2/image.rb, line 597
def crop!(x, y, w, h)
  ptr = self.class.create_image_ptr(w, h, alpha_blending?)
  SYM[:gdImageCopy].call(ptr, image_ptr, 0, 0, x, y, w, h)
  init_with_image(ptr)
end
draw() click to toggle source

Provide a drawing environment for a block. See GD2::Canvas.

# File lib/gd2/image.rb, line 429
def draw  #:yields: canvas
  yield Canvas.new(self)
  self
end
dup() click to toggle source

Duplicate this image, copying all pixels to a new image. Contrast with Image#clone which produces a shallow copy and shares internal pixel data.

# File lib/gd2/image.rb, line 257
def dup
  self.class.superclass.load(gd2(FMT_RAW))
end
each() click to toggle source

Iterate over each row of pixels in the image, returning an array of pixel values.

# File lib/gd2/image.rb, line 327
def each
  # optimize for speed
  get_pixel = SYM[:gdImageGetPixel]
  ptr = image_ptr
  (0...height).each do |y|
    row = (0...width).inject(Array.new(width)) do |row, x|
      row[x] = get_pixel.call(ptr, x, y).at(0)
      row
    end
    yield row
  end
end
export(filename, options = {}) click to toggle source

Export this image to a file with the given filename. The image format is determined by the :format option, or by the file extension (jpeg, png, gif, wbmp, gd, or gd2). Returns the size of the written image data. Additional options are as arguments for the Image#jpeg, Image#png, Image#wbmp, or Image#gd2 methods.

# File lib/gd2/image.rb, line 446
def export(filename, options = {})
  unless format = options.delete(:format)
    md = filename.match /\.([^.]+)\z/
    format = md ? md[1].downcase : nil
  end
  format = format.to_sym if format

  case format
  when :jpeg, :jpg
    write_sym = :gdImageJpeg
    args = [nil, options.delete(:quality) || -1]
  when :png
    write_sym = :gdImagePngEx
    args = [nil, options.delete(:level) || -1]
  when :gif
    write_sym = :gdImageGif
    args = [nil]
  when :wbmp
    write_sym = :gdImageWBMP
    fgcolor = options.delete(:fgcolor)
    raise ArgumentError, 'Missing required option :fgcolor' if fgcolor.nil?
    args = [color2pixel(fgcolor), nil]
  when :gd
    write_sym = :gdImageGd
    args = [nil]
  when :gd2
    write_sym = :gdImageGd2
    args = [nil, options.delete(:chunk_size) || 0,
      options.delete(:fmt) || FMT_COMPRESSED]
  else
    raise UnrecognizedImageTypeError,
      'Format (or file extension) is not recognized'
  end

  raise ArgumentError, "Unrecognized options #{options.inspect}" unless
    options.empty?

  File.open(filename, 'wb') do |file|
    args[args[0].nil? ? 0 : 1] = file
    SYM[write_sym].call(image_ptr, *args)
    file.pos
  end
end
gd() click to toggle source

Encode and return data for this image in “.gd” format. This is an internal format used by the gd library to quickly read and write images.

# File lib/gd2/image.rb, line 530
def gd
  ptr, rs = SYM[:gdImageGdPtr].call(image_ptr, 0)
  ptr.free = SYM[:gdFree]
  ptr[0, rs[1]]
end
gd2(fmt = FMT_COMPRESSED, chunk_size = 0) click to toggle source

Encode and return data for this image in “.gd2” format. This is an internal format used by the gd library to quickly read and write images. The specified fmt may be either GD2::FMT_RAW or GD2::FMT_COMPRESSED.

# File lib/gd2/image.rb, line 539
def gd2(fmt = FMT_COMPRESSED, chunk_size = 0)
  ptr, rs = SYM[:gdImageGd2Ptr].call(image_ptr, chunk_size, fmt, 0)
  ptr.free = SYM[:gdFree]
  ptr[0, rs[3]]
end
get_pixel(x, y) click to toggle source

Return the pixel value at image location (x, y).

# File lib/gd2/image.rb, line 304
def get_pixel(x, y)
  SYM[:gdImageGetPixel].call(@image_ptr, x, y).at(0)
end
Also aliased as: pixel
gif() click to toggle source

Encode and return data for this image in GIF format. Note that GIF only supports palette images; TrueColor images will be automatically converted to IndexedColor internally in order to create the GIF. Use Image#to_indexed_color to control this conversion more precisely.

# File lib/gd2/image.rb, line 512
def gif
  ptr, rs = SYM[:gdImageGifPtr].call(image_ptr, 0)
  ptr.free = SYM[:gdFree]
  ptr[0, rs[1]]
end
h() click to toggle source
Alias for: height
height() click to toggle source

Return the height of this image, in pixels.

# File lib/gd2/image.rb, line 287
def height
  image_ptr[:sy]
end
Also aliased as: h
interlaced=(bool) click to toggle source

Set whether this image will be stored in interlaced form when output as PNG or JPEG.

# File lib/gd2/image.rb, line 358
def interlaced=(bool)
  SYM[:gdImageInterlace].call(image_ptr, bool ? 1 : 0)
end
interlaced?() click to toggle source

Return true if this image will be stored in interlaced form when output as PNG or JPEG.

# File lib/gd2/image.rb, line 352
def interlaced?
  not image_ptr[:interlace].zero?
end
jpeg(quality = nil) click to toggle source

Encode and return data for this image in JPEG format. The quality argument should be in the range 0–95, with higher quality values usually implying both higher quality and larger sizes.

# File lib/gd2/image.rb, line 493
def jpeg(quality = nil)
  ptr, rs = SYM[:gdImageJpegPtr].call(image_ptr, 0, quality || -1)
  ptr.free = SYM[:gdFree]
  ptr[0, rs[1]]
end
merge_from(other, dst_x, dst_y, src_x, src_y, w, h, pct) click to toggle source

Merge a portion of another image into this one by the amount specified as pct (a percentage). A percentage of 1.0 is identical to Image#copy_from; a percentage of 0.0 is a no-op. Note that alpha channel information from the source image is ignored.

# File lib/gd2/image.rb, line 575
def merge_from(other, dst_x, dst_y, src_x, src_y, w, h, pct)
  SYM[:gdImageCopyMerge].call(image_ptr, other.image_ptr,
    dst_x, dst_y, src_x, src_y, w, h, pct.to_percent.round)
  self
end
optimize_palette() click to toggle source

Consolidate duplicate colors in this image, and eliminate all unused palette entries. This only has an effect on IndexedColor images, and is rather expensive. Returns the number of palette entries deallocated.

# File lib/gd2/image.rb, line 437
def optimize_palette
  # implemented by subclass
end
pixel(x, y) click to toggle source
Alias for: get_pixel
pixel2color(pixel) click to toggle source

Return a Color object for the given pixel value.

# File lib/gd2/image.rb, line 341
def pixel2color(pixel)
  Color.new_from_rgba(pixel)
end
png(level = nil) click to toggle source

Encode and return data for this image in PNG format. The level argument should be in the range 0–9 indicating the level of lossless compression (0 = none, 1 = minimal but fast, 9 = best but slow).

# File lib/gd2/image.rb, line 502
def png(level = nil)
  ptr, rs = SYM[:gdImagePngPtrEx].call(image_ptr, 0, level || -1)
  ptr.free = SYM[:gdFree]
  ptr[0, rs[1]]
end
polar_transform(radius) click to toggle source

Like Image#polar_transform! except a new image is returned.

# File lib/gd2/image.rb, line 652
def polar_transform(radius)
  clone.polar_transform!(radius)
end
polar_transform!(radius) click to toggle source

Transform this image into a new image of width and height radius × 2, in which the X axis of the original has been remapped to θ (angle) and the Y axis of the original has been remapped to ρ (distance from center). Note that the original image must be square.

# File lib/gd2/image.rb, line 644
def polar_transform!(radius)
  raise 'Image must be square' unless width == height
  ptr = SYM[:gdImageSquareToCircle].call(image_ptr, radius)[0]
  raise LibraryError unless ptr
  init_with_image(ptr)
end
resize(w, h, resample = true) click to toggle source

Like Image#resize! except a new image is returned.

# File lib/gd2/image.rb, line 636
def resize(w, h, resample = true)
  clone.resize!(w, h, resample)
end
resize!(w, h, resample = true) click to toggle source

Resize this image to the given dimensions. If resample is true, the image pixels will be resampled; otherwise they will be stretched or shrunk as necessary without resampling.

# File lib/gd2/image.rb, line 625
def resize!(w, h, resample = true)
  ptr = self.class.create_image_ptr(w, h, false)
  SYM[resample ? :gdImageCopyResampled : :gdImageCopyResized].call(
    ptr, image_ptr, 0, 0, 0, 0, w, h, width, height)
  alpha_blending = alpha_blending?
  init_with_image(ptr)
  self.alpha_blending = alpha_blending
  self
end
rotate(angle, axis_x = width / 2.0, axis_y = height / 2.0) click to toggle source

Like Image#rotate! except a new image is returned.

# File lib/gd2/image.rb, line 591
def rotate(angle, axis_x = width / 2.0, axis_y = height / 2.0)
  clone.rotate!(angle, axis_x, axis_y)
end
rotate!(angle, axis_x = width / 2.0, axis_y = height / 2.0) click to toggle source

Rotate this image by the given angle (in radians) about the given axis coordinates. Note that some of the edges of the image may be lost.

# File lib/gd2/image.rb, line 583
def rotate!(angle, axis_x = width / 2.0, axis_y = height / 2.0)
  ptr = self.class.create_image_ptr(width, height, alpha_blending?)
  SYM[:gdImageCopyRotated].call(ptr, image_ptr,
    axis_x.to_f, axis_y.to_f, 0, 0, width, height, angle.to_degrees.round)
  init_with_image(ptr)
end
save_alpha=(bool) click to toggle source

Set whether this image will be stored with full alpha channel information when output as PNG.

# File lib/gd2/image.rb, line 384
def save_alpha=(bool)
  SYM[:gdImageSaveAlpha].call(image_ptr, bool ? 1 : 0)
end
save_alpha?() click to toggle source

Return true if this image will be stored with full alpha channel information when output as PNG.

# File lib/gd2/image.rb, line 378
def save_alpha?
  not image_ptr[:saveAlphaFlag].zero?
end
set_pixel(x, y, value) click to toggle source

Set the pixel value at image location (x, y).

# File lib/gd2/image.rb, line 310
def set_pixel(x, y, value)
  SYM[:gdImageSetPixel].call(@image_ptr, x, y, value)
  nil
end
sharpen(pct) click to toggle source

Sharpen this image by pct (a percentage) which can be greater than 1.0. Transparency/alpha channel are not altered. This has no effect on IndexedColor images.

# File lib/gd2/image.rb, line 659
def sharpen(pct)
  self
end
size() click to toggle source

Return the size of this image as an array [width, height], in pixels.

# File lib/gd2/image.rb, line 293
def size
  [width, height]
end
to_indexed_color(colors = MAX_COLORS, dither = true) click to toggle source

Return this image as an IndexedColor image, creating a copy if necessary. colors indicates the maximum number of palette colors to use, and dither controls whether dithering is used.

# File lib/gd2/image.rb, line 671
def to_indexed_color(colors = MAX_COLORS, dither = true)
  obj = IndexedColor.allocate
  ptr = SYM[:gdImageCreatePaletteFromTrueColor].call(
    to_true_color.image_ptr, dither ? 1 : 0, colors)[0]
  raise LibraryError unless ptr

  obj.init_with_image(ptr)

  # fix for gd bug where image->open[] is not properly initialized
  (0...ptr[:colorsTotal]).each do |i|
    ptr[:"open[#{i}]"] = 0
  end

  obj
end
to_true_color() click to toggle source

Return this image as a TrueColor image, creating a copy if necessary.

# File lib/gd2/image.rb, line 664
def to_true_color
  self
end
transparent() click to toggle source

Return the transparent color for this image, or nil if none has been set.

# File lib/gd2/image.rb, line 390
def transparent
  pixel = image_ptr[:transparent]
  pixel == -1 ? nil : pixel2color(pixel)
end
transparent=(color) click to toggle source

Set or unset the transparent color for this image.

# File lib/gd2/image.rb, line 396
def transparent=(color)
  SYM[:gdImageColorTransparent].call(image_ptr,
    color.nil? ? -1 : color2pixel(color))
end
true_color?() click to toggle source

Return true if this image is a TrueColor image.

# File lib/gd2/image.rb, line 275
def true_color?
  kind_of?(TrueColor)
  # self.class.image_true_color?(image_ptr)
end
uncrop(x1, y1 = x1, x2 = x1, y2 = y1) click to toggle source

Like Image#uncrop! except a new image is returned.

# File lib/gd2/image.rb, line 618
def uncrop(x1, y1 = x1, x2 = x1, y2 = y1)
  clone.uncrop!(x1, y1, x2, y2)
end
uncrop!(x1, y1 = x1, x2 = x1, y2 = y1) click to toggle source

Expand the left, top, right, and bottom borders of this image by the given number of pixels.

# File lib/gd2/image.rb, line 610
def uncrop!(x1, y1 = x1, x2 = x1, y2 = y1)
  ptr = self.class.create_image_ptr(x1 + width + x2, y1 + height + y2,
    alpha_blending?)
  SYM[:gdImageCopy].call(ptr, image_ptr, x1, y1, 0, 0, width, height)
  init_with_image(ptr)
end
w() click to toggle source
Alias for: width
wbmp(fgcolor) click to toggle source

Encode and return data for this image in WBMP format. WBMP currently supports only black and white images; the specified fgcolor will be used as the foreground color (black), and all other colors will be considered “background” (white).

# File lib/gd2/image.rb, line 522
def wbmp(fgcolor)
  ptr, rs = SYM[:gdImageWBMPPtr].call(image_ptr, 0, color2pixel(fgcolor))
  ptr.free = SYM[:gdFree]
  ptr[0, rs[1]]
end
width() click to toggle source

Return the width of this image, in pixels.

# File lib/gd2/image.rb, line 281
def width
  image_ptr[:sx]
end
Also aliased as: w
with_clipping(x1, y1, x2, y2) click to toggle source

Temporarily set the clipping rectangle during the execution of a block. Pixels outside this rectangle will not be modified by drawing or copying operations.

# File lib/gd2/image.rb, line 411
def with_clipping(x1, y1, x2, y2)   #:yields: image
  clip = clipping
  set_clip = SYM[:gdImageSetClip]
  begin
    set_clip.call(image_ptr, x1, y1, x2, y2)
    yield self
    self
  ensure
    set_clip.call(image_ptr, *clip)
  end
end

[Validate]

Generated with the Darkfish Rdoc Generator 2.