Miscellaneous classes

Table of Contents

Struct classes

Fill classes

Exception classes

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

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

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 Geometry

new

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

Description

Constructs a new Geometry object. A Geometry object is the equivalent of a geometry string. A Geometry object can be used almost anywhere a geometry string can be used.

Attributes

A geometry string has the general form "WxH+x+y[!@%<>]. In a Geometry object, the width attribute specifies the W value. The height attribute specifies the H value. The x and y attributes specify the x and y values, respectively. If any of these attributes is omitted the default is nil or 0.

The flag attribute is one of the constants shown here:

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

class Pixel

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.

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 hue, saturation, and luminosity values.

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

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

class Point

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

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

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
ffset from the left edge of the image
y
Offset from the top edge of the image

class Segment

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

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

GradientFill example

class HatchFill

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

HatchFill example

class TextureFill

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

TextureFill example

Exception classes

class ImageMagickError

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