RMagick: Miscellaneous classes

###### RMagick User's Guide and Reference

# Miscellaneous classes

## The Image::View class

### Introduction

A view is a rectangle in an image. Within the view pixels can be addressed by specifying their `[i][j]` coordinates. The i, j index values can identify a single pixel or multiple pixels. Pixels can be accessed or modified individually or collectively. Pixel channels (that is, the red, green, blue, and opacity components) can be accessed or modified individually or collectively. The sync method stores modified pixels back into the image.

### class Image::View < Object

#### new

Image::View.new(img, x, y, width, height) -> aView

##### Description

The easiest way to use an `Image::View` object is to create it with the Image#view method, which provides a block-scoped view and automatic sync'ing. You probably won't want to create a view by calling `new`.

##### Arguments

img
  The image from which the view is taken.
x, y
  The x- and y-offsets of the view relative to the top-left corner of the image. Within the view, pixel addresses are relative to the top-left corner of the view.
width, height
  The number of columns and the number of rows in the view.

It is an error to specify a view that exceeds the boundaries of the image.

#### [][]

view[i][j] -> aPixel or anArray

##### Description

Return one or more pixels in the view. If i and j are each a single integer value, returns a single pixel. For any other indexes, returns an array of one or more pixels. If any index exceeds the boundaries of the view, raises `IndexError`.

##### Arguments

The i index identifies a set of rows in the view. The j index identifies a set of columns in the view. The pixels that are returned are the intersection of these two sets. The indexes can be:

omitted
  If i is omitted, all the rows are used. If `j` is omitted, all the columns are used.
an integer
  or an object that can be converted to an integer. A single integer identifies a single row or column. Identify a single pixel by specifying integers for both indexes. If the index is negative, counts from the bottom row or right column of the view.
start, length
  Identifies the set of `length` rows or columns starting with `start`. If `start` is negative, starts at the bottom row or right column of the view.
an object that responds to `each`
  The index may be any object that responds to `each` by returning a sequence of objects that can be converted to integers. An array with integer values or a range of integers are two examples.

##### Examples

      # Get the 2nd pixel in the 4th row of the view.
      pixel = view[3][1]  # returns a pixel
      # Returns an array with only one value
      pixels = view[[3]][[1]]
      # Get all the pixels in the 4th row
      pixels = view[3][]
      # Use arrays to specify a non-contiguous set of rows and columns
      pixels = view[[1,3,5]][[2,4,6]]
      # Use ranges to specify a contigous set of rows and columns
      pixels = view[1..5][2..6]

#### [][].red
[][].green
[][].blue
[][].opacity

[i][j].red -> anInteger or anArray
[i][j].green -> anInteger or anArray
[i][j].blue -> anInteger or anArray
[i][j].opacity -> anInteger or anArray

##### Description

If the indexes identify a single pixel, these methods return the value of the red, green, blue, or opacity channel of that pixel. If the indexes identify more than one pixel, these methods return an array of values. See `[][]` for a description of possible index arguments.

##### Examples

      # Get the value of the green channel of
      # the top-left pixel in the view.
      view[0][0] = Pixel(0,128,255)
      g = view[0][0].green  # returns 128

      # Get the maximum value of the red channel
      # for all the pixels in the top row of the view.
      m = view[0][].red.max

#### [][]=

view[i][j] = rvalue -> `nil`

##### Description

Replaces each pixel identified by the indexes with a duplicate of rvalue. The rvalue is either a Pixel object or a color name. If `rvalue` is a color name, calls `Pixel.from_color` to create a pixel.

##### Arguments

The indexes are the same as `[][]`, above.

rvalue
  Either a pixel or a color name.

#### [][].red=
[][].green=
[][].blue=
[][].opacity=

[i][j].red = anInteger -> `nil`
[i][j].green = anInteger -> `nil`
[i][j].blue = anInteger -> `nil`
[i][j].opacity = anInteger -> `nil`

##### Description

Assigns anInteger to the red, green, blue, or opacity channel of the pixel or pixels identified by the indexes.

##### Examples

      # Set the red channel of all the pixels in the 2nd
      # row of the view to MaxRGB
      view[1][].red = MaxRGB
      # Set the green channel of the pixel at [20][30] to
      # half that of its left-hand neighbor.
      view[20][30].green = view[20][29].green * 0.5

#### sync

view.sync(force=`false`) -> `true` or `false`

##### Description

If any of the pixels in the view have been modified, this method stores them in the image. If no pixels have been modified, this method has no effect.

##### Arguments

force
  If `true`, forces the view pixels to be stored in the image even if none have been modified.

##### Returns

Returns `true` if the pixels were stored in the image either because the `dirty` flag was `true` or `force` was `true`, `false` otherwise.

#### dirty
dirty=

view.dirty -> `true` or `false`
view.dirty = `true` or `false`

##### Description

Any modification to a pixel in the view causes the `dirty` attribute to be set to `true`. You can (although normally you don't need to) set `dirty=true` to force `sync` to store the pixels in the image, or set `dirty=false` to keep `sync` from storing the pixels.

#### x
y
width
height

x -> anInteger
y -> anInteger
width -> anInteger
height -> anInteger

##### Description

The x, y, width, and height arguments specified when the view was created.

## The Geometry class

### Introduction

The Geometry class contains the same information as an ×Magick geometry string. Geometry objects are interchangable with geometry strings.

### class Geometry < Object

#### new

Geometry.new(width=nil, height=nil, x=nil, y=nil, flag=nil) -> aGeometry

##### Description

Constructs a new `Geometry` object.

##### Attributes

A geometry string has the general form "WxH+x+y[!@%<>]. In a `Geometry` object,

width
  specifies the W value
height
  specifies the H value
x, y
  specify the x and y values, respectively
flag
  one of the constants shown in this table:

Geometry flag constants
Constant name | Geometry string flag | Explanation
PercentGeometry | % | Normally the attributes are treated as pixels. Use this flag when the `width` and `height` attributes represent percentages. For example, 125x75 means 125% of the height and 75% of the width. The `x` and `y` attributes are not affected by this flag.
AspectGeometry | ! | Use this flag when you want to force the new image to have exactly the size specified by the the `width` and `height` attributes.
LessGeometry | < | Use this flag when you want to change the size of the image only if both its width and height are smaller the values specified by those attributes. The image size is changed proportionally.
GreaterGeometry | > | Use this flag when you want to change the size of the image if either its width and height exceed the values specified by those attributes. The image size is changed proportionally.
AreaGeometry | @ | This flag is useful only with a single `width` attribute. When present, it means the `width` attribute represents the total area of the image in pixels.

If any attribute is omitted the default is nil or 0.

##### Example

    g = Magick::Geometry.new(100,200,nil,nil,Magick::AspectGeometry)

#### from_s

Geometry.from_s(string) -> aGeometry

##### Description

Constructs a new `Geometry` object from a geometry string.

#### to_s

geometry.to_s() -> aString

##### Description

Returns the string equivalent of the `Geometry` object..

## The Pixel class

### Introduction

A pixel describes the smallest individually addressable part of an image. In the RBG colorspace, a pixel's color is described by its intensity in the red, green, and blue channels. Its opacity is described by its intensity in the opacity (also called alpha, or matte) channel. In the CMYK colorspace a pixel's color is described by its intensity in the cyan, magenta, yellow and black (K) channels. Intensity is a value between 0 and MaxRGB.

Usually, RMagick methods operate on entire images or on groups of pixels that have been selected by their position or color. Some methods, such as pixel_color and view, operate on individual pixels or even on the RGBA (or CMYK) components thereof.

### class Pixel < Object
mixes in Comparable, Observable

#### new

Pixel.new(red, green, blue, opacity) -> aPixel

##### Description

Constructs a pixel object from the specified red, green, blue, and opacity intensities. The intensity is a number between 0 and MaxRGB.

##### Attributes

red, green, blue
  The red, green, and blue intensities of the pixel, respectively. If the colorspace is CMYKColorspace, these attributes are interpreted as the cyan, magenta, and yellow intensities.
opacity
  The opacity level. Higher intensities are more transparent. If the colorspace is CMYKColorspace, this attribute is interpreted as the black intensity.
cyan, magenta, yellow, black
  These attributes are aliases for `red`, `green`, `blue`, and `opacity`, respectively.

#### from_color

Pixel.from_color(color_name) -> aPixel

##### Description

Constructs a new Pixel object from the color name. Raises ArgumentError if the name is unknown.

#### from_HSL

Pixel.from_HSL([hue, saturation, luminosity]) -> aPixel

##### Description

Constructs a pixel object from the specified array of 3 values: hue, saturation, and luminosity.

#### <=>

pixel1 <=> pixel2 -> -1, 0, or 1

##### Description

Returns -1, 0, or 1 depending on if pixel1 is "less than," equal, or "greater than" the pixel2.

Since there is no way to rank order pixels, and thus determine if one pixel is "greater than" or "less than" another, this method uses an arbitrary algorithm that ensures these two conditions:

1. pixels with equal RGBA (or CMYK) values compare equal, and
2. comparing the same two unequal pixels always returns the same result.

##### Returns

-1, 0, or 1

##### See also

fcmp

#### fcmp

pixel.fcmp(aPixel, fuzz=0.0, colorspace=RGBColorspace) -> `true` or `false`

##### Description

Returns true if the argument is the same color as pixel.

##### Arguments

pixel
  The pixel to which the receiver is compared.
fuzz
  The amount of fuzz to allow before the colors are considered to be different.
colorspace
  If the pixels are in the CMYK colorspace, specify Magick::CMYKColorspace.

##### Returns

`true` or `false`

##### See also

<=>

#### intensity

pixel.intensity() -> anInteger

##### Description

Returns the intensity of the pixel. The intensity is computed as 0.299*R+0.587*G+0.114*B.

#### to_color

pixel.to_color(compliance=AllCompliance, matte=`false`, depth=`QuantumDepth`) -> aString

##### Description

Returns the color name corresponding the the pixel values. If there is no such named color in the specified color standard, returns a string in the form "#RRGGBBOO" or, if the depth is 16, "#RRRRGGGGBBBBOOOO".

##### Arguments

compliance
  A ComplianceType constant. The default value of AllCompliance causes `to_color` to search for a color name in any of the 3 defined color standards.
matte
  If false, the pixel's opacity attribute is ignored.
depth
  An image depth. The default is the quantum depth used when ×Magick was compiled. The values 16 and 32 can be used only when ×Magick was compiled with the appropriate QuantumDepth.

##### See also

Compare this method to Image#to_color, in which the matte and depth values are taken from an image.

#### to_HSL

pixel.to_HSL -> anArray

##### Description

Converts the RGB representation of the pixel to hue, saturation, and luminosity values.

##### Returns

An array of the form `[hue, saturation, luminosity]`.

## Struct classes

### Introduction

These classes are created by the Struct class and are used to create objects used as attribute and argument values in other RMagick classes. Like all the classes created by Struct, these classes define both getter and setter methods for their attributes. That is, for an attribute x both the `x` and `x=` methods are defined.

The `Pixel` and `Geometry` classes define additional constructors and conversion methods.

### class AffineMatrix < Struct

#### new

AffineMatrix.new(sx, rx, ry, sy, tx, ty) -> anAffineMatrix

##### Description

An AffineMatrix object describes a coordinate transformation. This object is used as an argument to the Image#affine_transform, Image#composite_affine, and Draw#affine methods.

##### Attributes

sx, sy
  The amount of scaling on the x- and y- axes.
rx, ry
  The amount of rotation on the x- and y-axes, in radians.
tx, ty
  The amount of translation on the x- and y-axes, in pixels.

### class Chromaticity < Struct

#### new

Chromaticity.new(red_primary, green_primary, blue_primary, white_point) -> aChromaticity

##### Description

A Chromaticity object represents chromaticity values for the Image#chromaticity attribute.

##### Attributes

The attribute values are Primary objects.

red_primary
  Red primary point (e.g. red_primary.x=0.64, red_primary.y=0.33)
green_primary
  Green primary point (e.g. green_primary.x=0.3, green_primary.y=0.6)
blue_primary
  Blue primary point (e.g. blue_primary.x=0.15, blue_primary.y=0.06)
white_point
  White point (e.g. white_point.x=0.3127, white_point.y=0.329)

### class Point < Struct

#### new

Point.new(x, y) -> aPoint

##### Description

The value of the `pixels_per_em` attribute in the TypeMetric struct returned by Draw#get_type_metrics is a `Point` object..

##### Attributes

x
  Character width
y
  Character height

### class Primary < Struct

#### new

Primary.new(x, y, z) -> aPrimary

##### Description

See class Chromaticity.

##### Attributes

x
  X ordinate
y
  Y ordinate
z
  Z ordinate. This attribute is always ignored.

### class Rectangle < Struct

#### new

Rectangle.new(width, height, x, y) -> aRectangle

##### Description

The value of the Image#tile_info and Image#bounding_box attributes.

##### Attributes

width
  Rectangle width
height
  Rectangle height
x
  Offset from the left edge of the image
y
  Offset from the top edge of the image

### class Segment < Struct

#### new

Segment.new(x1, y1, x2, y2) -> aSegment

##### Description

The value of the `bounds` attribute in the TypeMetric class.

##### Attributes

x1, y1, x2, y2

## Fill classes

### Introduction

The Image#new and ImageList#new_image methods accept a `Fill` object as an optional third argument. A `Fill` object is an instance of a Fill class. Fill classes are designed to support custom background fills. Each `Fill` class defines only two methods, `initialize` and `fill`. The `initialize` method is called from the application to create an instance of the fill class. It accepts any arguments and does whatever is necessary to create the fill. The `fill` method is called from the initialize method of the new image object, after the image is completely initialized. The `fill` method gets the image as its only argument and sends whatever methods are necessary to the image to fill the image's background.

RMagick supplies three Fill classes, `HatchFill`, `GradientFill`, and `TextureFill`. These classes are explained below. The `HatchFill` class is intended as an example of how to write a `Fill` class and is written in pure Ruby. You can read it in RMagick.rb.

### class GradientFill < Object

#### new

GradientFill.new(x1, y1, x2, y2, start_color, end_color) -> aGradientFill

##### Description

Creates a gradient fill. The x1, y1, and x2, y2 arguments describe either a line or a point. If x1 != x2 or y1 != y2, then the arguments describe the starting line for the gradient. The gradient will start with start_color at the starting line and gradually transform to end_color as the distance increases from the starting line.

If x1 == x2 and y1 == y2, the gradient radiates from the specified point, gradually transforming from start_color to end_color.

The line or point does not have to lie within the image bounds.

##### Arguments

x1, y1
  One of the starting line end-points.
x2, y2
  The other end-point on the starting line.
start_color
  The color at the starting line.
end_color
  The color to which the gradient transforms.

##### Example

### class HatchFill < Object

#### new

HatchFill.new(background_color, hatch_color='white', dist=10) -> aHatchFill

#### Description

Creates a cross-hatched fill.

#### Arguments

background_color
  The image background color.
hatch_color
  The color of the cross-hatch lines.
dist
  The distance between cross-hatch lines, in pixels.

#### Example

### class TextureFill < Object

#### new

TextureFill.new(texture_image) -> aTextureFill

##### Description

Creates a texture fill by tiling the texture_image to fill the image.

##### Arguments

The texture to be used as the background. May be an image or imagelist. If texture_image is an imagelist, uses the current image.

##### Example

## Exception classes

### class ImageMagickError < StandardError

#### Description

When an ×Magick function returns an error condition, RMagick raises an `ImageMagickError` exception.

#### Attributes

magick_location
  With GraphicsMagick 1.1, this attribute contains a string that indicates the source file (module), function and line number in which GraphicsMagick raised the error. The string is in the form `<function> at <module>:<line>`. (Get-only.)