Class: GD2::Image

Class | GD2::Image
In: | lib/gd2/image.rb
Parent: | Object

# 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 = {})

### Methods

== [] []= alpha_blending= alpha_blending? aspect clipping clips? color2pixel compare copy_from copy_from_rotated crop crop! draw dup each export gd gd2 get_pixel gif h height import interlaced= interlaced? jpeg load merge_from new optimize_palette pixel pixel2color png polar_transform polar_transform! resize resize! rotate rotate! save_alpha= save_alpha? set_pixel sharpen size to_indexed_color to_true_color transparent transparent= true_color? uncrop uncrop! w wbmp width with_clipping

### Included Modules

Enumerable

### Classes and Modules

Class GD2::Image::IndexedColor
Class GD2::Image::TrueColor
Class GD2::Image::UnrecognizedImageTypeError

### External Aliases

new | -> | []

### Attributes

palette | [R] | The Palette object for this image

### Public Class methods

import(filename, options = {}) {|image| ...}

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.

load(src) {|image| ...}

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.

new(w, h) {|image| ...}

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.

### Public Instance methods

==(other)

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

[](x, y)

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

[]=(x, y, color)

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

alpha_blending=(bool)

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

alpha_blending?()

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.

aspect()

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

clipping()

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

clips?(x, y)

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

color2pixel(color)

Return a pixel value for the given `color` object.

compare(other)

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.

copy_from(other, dst_x, dst_y, src_x, src_y, dst_w, dst_h, src_w = nil, src_h = nil)

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.

copy_from_rotated(other, dst_x, dst_y, src_x, src_y, w, h, angle)

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.

crop(x, y, w, h)

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

crop!(x, y, w, h)

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

draw( {|canvas| ...}

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

dup()

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

each() {|row| ...}

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

export(filename, options = {})

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.

gd()

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.

gd2(fmt = FMT_COMPRESSED, chunk_size = 0)

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.

get_pixel(x, y)

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

gif()

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.

h()

Alias for height

height()

Return the height of this image, in pixels.

interlaced=(bool)

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

interlaced?()

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

jpeg(quality = nil)

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.

merge_from(other, dst_x, dst_y, src_x, src_y, w, h, pct)

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.

optimize_palette()

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.

pixel(x, y)

Alias for get_pixel

pixel2color(pixel)

Return a Color object for the given `pixel` value.

png(level = nil)

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).

polar_transform(radius)

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

polar_transform!(radius)

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.

resize(w, h, resample = true)

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

resize!(w, h, resample = true)

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.

rotate(angle, axis_x = width / 2.0, axis_y = height / 2.0)

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

rotate!(angle, axis_x = width / 2.0, axis_y = height / 2.0)

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.

save_alpha=(bool)

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

save_alpha?()

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

set_pixel(x, y, value)

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

sharpen(pct)

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.

size()

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

to_indexed_color(colors = MAX_COLORS, dither = true)

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.

to_true_color()

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

transparent()

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

transparent=(color)

Set or unset the transparent color for this image.

true_color?()

Return true if this image is a TrueColor image.

uncrop(x1, y1 = x1, x2 = x1, y2 = y1)

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

uncrop!(x1, y1 = x1, x2 = x1, y2 = y1)

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

w()

Alias for width

wbmp(fgcolor)

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).

width()

Return the width of this image, in pixels.

with_clipping(x1, y1, x2, y2) {|image| ...}

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

[Validate]