RMagick 0.0.0 User's Guide and Reference

Constants

Constants

Miscellaneous constants

Long_version

An extended form of the Version constant with the format shown here:
This is RMagick 2.0.0 ($Date: 2009/09/05 20:10:15 $) Copyright (C) 2008 by Timothy P. Hunter
Built with ImageMagick 6.3.7 01/05/08 Q16 http://www.imagemagick.org
Built for ruby 1.8.6
Web page: http://rmagick.rubyforge.org
Email: rmagick@rubyforge.org

Magick_version

The ImageMagick version string. This has the form:
@(#)ImageMagick X.Y.Z MM/DD/YY Q:16 http://www.imagemagick.org

MANAGED_MEMORY

If true, RMagick is using Ruby managed memory for all allocations. If false, RMagick allocates memory for objects directly from the operating system. You can enable RMagick to use Ruby managed memory (when built with ImageMagick 6.4.0-11 and later) by setting

RMAGICK_ENABLE_MANAGED_MEMORY = true

before requiring RMagick.

QuantumRange

The maximum value of a Quantum. A quantum is one of the red, green, blue, or opacity elements of a pixel in the RGB colorspace, or cyan, yellow, magenta, or black elements in the CYMK colorspace.

MaxRGB (deprecated)

Same as QuantumRange.

QuantumDepth

The number of bits in a quantum. The relationship between QuantumDepth and QuantumRange is summarized in this table.

QuantumDepth	QuantumRange
8	255
16	65535
32	4294967295

Version

The RMagick version string. This has the form:
RMagick 2.0.0

AlignType

Specify text alignment. See align=, text_align.

UndefinedAlign

No alignment specified. Equivalent to LeftAlign.

LeftAlign

Align the leftmost part of the text to the starting point.

CenterAlign

Center the text around the starting point.

RightAlign

Align the rightmost part of the text to the starting point.

ChannelType

Specify an image channel. A channel is a color component of a pixel. In the RGB colorspace the channels are red, green, and blue. There may also be an alpha (transparency/opacity) channel. In the CMYK colorspace the channels area cyan, magenta, yellow, and black. In the HSL colorspace the channels are hue, saturation, and lightness. In the Gray colorspace the only channel is gray. See Image#channel and Image::Info#channel=.

UndefinedChannel

RedChannel

GreenChannel

BlueChannel

CyanChannel

MagentaChannel

YellowChannel

BlackChannel

OpacityChannel

AllChannels

In the RGB colorspace, the red, blue, green, and alpha channels. In the CMYK colorspace, the cyan, magenta, yellow, and black channels.

GrayChannel

AlphaChannel

Same as OpacityChannel

DefaultChannels

Same as AllChannels, excluding OpacityChannel

HueChannel

LuminosityChannel

SaturationChannel

ClassType

Specify the image storage class. See class_type.

UndefinedClass

No storage class has been specified.

DirectClass

Image is composed of pixels which represent literal color values.

PseudoClass

Image is composed of pixels which specify an index in a color palette.

ColorspaceType

Specify the colorspace that quantization (color reduction and mapping) is done under or to specify the colorspace when encoding an output image. Colorspaces are ways of describing colors to fit the requirements of a particular application (e.g. Television, offset printing, color monitors).  Color reduction, by default, takes place in the RGBColorspace. Empirical evidence suggests that distances in color spaces such as YUVColorspace or YIQColorspace correspond to perceptual color differences more closely than do distances in RGB space. These color spaces may give better results when color reducing an image.

When encoding an output image, the colorspaces RGBColorspace, CMYKColorspace, and GRAYColorspace may be specified. The CMYKColorspace option is only applicable when writing TIFF, JPEG, and Adobe Photoshop bitmap (PSD) files. See colorspace.

Each version of ImageMagick defines a subset of the colorspaces listed below. To list the subset supported by your version, issue the command:

ruby -rRMagick -e"Magick::ColorspaceType.values {|cs| puts cs}"

UndefinedColorspace

No colorspace has been specified.

CMYColorspace

CMYKColorspace

Cyan-Magenta-Yellow-Black colorspace. CYMK is a subtractive color system used by printers and photographers for the rendering of colors with ink or emulsion, normally on a white surface.

GRAYColorspace

Full-range grayscale

HSBColorspace

HSLColorspace

Hue, saturation, luminosity

HWBColorspace

Hue, whiteness, blackness

LABColorspace

LogColorspace

OHTAColorspace

RGBColorspace

Red-Green-Blue colorspace

SRGBColorspace

Kodak PhotoCD sRGB. In ImageMagick, this constant is named sRGBColorspace, but since Ruby constants must start with an uppercase letter, I had to change it.

TransparentColorspace

The Transparent color space behaves uniquely in that it preserves the matte channel of the image if it exists.

XYZColorspace

CIE XYZ

YCbCrColorspace

YCCColorspace

Kodak PhotoCD PhotoYCC

YIQColorspace

YPbPrColorspace

YUVColorspace

Y-signal, U-signal, and V-signal colorspace. YUV is most widely used to encode color for use in television transmission.

The colorspaces in this group are typically associated with the DPX and Cineon image formats used in the motion picture industry.

Rec601LumaColorspace

Luma (Y) according to ITU-R 601

Rec601YCbCrColorspace

YCbCr according to ITU-R 601

Rec709LumaColorspace

Luma (Y) according to ITU-R 709

Rec709YCbCrColorspace

YCbCr according to ITU-R 709

ComplianceType

Specify the color standard from which color names are chosen. See to_color.

SVGCompliance

Adhere to SVG color standard.

X11Compliance

Adhere to X11 color standard.

XPMCompliance

Adhere to XPM color standard.

AllCompliance

The union of the 3 color standards.

CompositeOperator

Select the image composition algorithm used to compose a composite image with a image. By default, each of the composite image pixels are replaced by the corresponding image tile pixel. Specify CompositeOperator to select a different algorithm. See composite.

UndefinedCompositeOp

No composite operator has been specified.

AddCompositeOp

The result of composite image + image, with overflow wrapping around (mod 256).

AtopCompositeOp

The result is the same shape as image, with composite image obscuring image where the image shapes overlap. Note that this differs from OverCompositeOp because the portion of composite image outside of image's shape does not appear in the result.

BlurCompositeOp

?

BumpmapCompositeOp

The result image shaded by composite image.

ChangeMaskCompositeOp

Replace any destination pixel that is the similar to the source image's pixel (as defined by the current fuzz factor), with transparency.

ClearCompositeOp

Make the target image transparent. The composite image is ignored.

ColorBurnCompositeOp

Darkens the destination color to reflect the source color. Painting with white produces no change.

ColorDodgeCompositeOp

Brightens the destination color to reflect the source color. Painting with black produces no change.

ColorizeCompositeOp

Each pixel in the result image is the combination of the brightness of the target image and the saturation and hue of the composite image. This is the opposite of LuminizeCompositeOp.

CopyCompositeOp

Replace the target image with the composite image.

CopyBlackCompositeOp

Copy the black channel from the composite image to the target image.

CopyBlueCompositeOp

Copy the blue channel from the composite image to the target image.

CopyCyanCompositeOp

Copy the cyan channel from the composite image to the target image.

CopyGreenCompositeOp

Copy the green channel from the composite image to the target image.

CopyMagentaCompositeOp

Copy the magenta channel from the composite image to the target image.

CopyOpacityCompositeOp

If the composite image's matte attribute is true, copy the opacity channel from the composite image to the target image. Otherwise, set the target image pixel's opacity to the intensity of the corresponding pixel in the composite image.

CopyRedCompositeOp

Copy the red channel from the composite image to the target image.

CopyYellowCompositeOp

Copy the yellow channel from the composite image to the target image.

DarkenCompositeOp

Replace target image pixels with darker pixels from the composite image.

DifferenceCompositeOp

The result of abs(composite image - image). This is useful for comparing two very similar images.

DisplaceCompositeOp

Displace target image pixels as defined by a displacement map. The operator used by the displace method.

DissolveCompositeOp

The operator used in the dissolve method.

DistortCompositeOp

?

DivideCompositeOp

?

DstCompositeOp

The destination is left untouched.

DstAtopCompositeOp

The part of the destination lying inside of the source is composited over the source and replaces the destination.

DstInCompositeOp

The part of the destination lying inside of the source replaces the destination.

DstOutCompositeOp

The part of the destination lying outside of the source replaces the destination.

DstOverCompositeOp

The destination is composited over the source and the result replaces the destination.

ExclusionCompositeOp

Produces an effect similar to that of 'difference', but appears as lower contrast. Painting with white inverts the destination color. Painting with black produces no change.

HardLightCompositeOp

Multiplies or screens the colors, dependent on the source color value. If the source color is lighter than 0.5, the destination is lightened as if it were screened. If the source color is darker than 0.5, the destination is darkened, as if it were multiplied. The degree of lightening or darkening is proportional to the difference between the source color and 0.5. If it is equal to 0.5 the destination is unchanged. Painting with pure black or white produces black or white.

HueCompositeOp

Each pixel in the result image is the combination of the hue of the target image and the saturation and brightness of the composite image.

InCompositeOp

The result is simply composite image cut by the shape of image. None of the image data of image is included in the result.

LightenCompositeOp

Replace target image pixels with lighter pixels from the composite image.

LinearBurnCompositeOp

Same as LinearDodgeCompositeOp, but also subtract one from the result. Sort of a additive 'Screen' of the images.

LinearDodgeCompositeOp

This is equivelent to PlusCompositeOp in that the color channels are simply added, however it does not "plus" the alpha channel, but uses the normal OverCompositeOp alpha blending, which transparencies are involved. Produces a sort of additive multiply-like result.

LinearLightCompositeOp

Increase contrast slightly with an impact on the foreground's tonal values.

LuminizeCompositeOp

Each pixel in the result image is the combination of the brightness of the composite image and the saturation and hue of the target image. This is the opposite of ColorizeCompositeOp.

MinusCompositeOp

The result of composite image - image, with overflow cropped to zero. The matte chanel is ignored (set to 255, full coverage).

ModulateCompositeOp

Used by the watermark method.

MultiplyCompositeOp

Multiplies the color of each target image pixel by the color of the corresponding composite image pixel. The result color is always darker.

NoCompositeOp

No composite operator has been specified.

OutCompositeOp

The resulting image is composite image with the shape of image cut out.

OverCompositeOp

The result is the union of the the two image shapes with composite image obscuring image in the region of overlap. The matte channel of the composite image is respected, so that if the composite pixel is part or all transparent, the corresponding image pixel will show through.

OverlayCompositeOp

Multiplies or screens the colors, dependent on the destination color. Source colors overlay the destination whilst preserving its highlights and shadows. The destination color is not replaced, but is mixed with the source color to reflect the lightness or darkness of the destination.

PegtopLightCompositeOp

Almost equivalent to SoftLightCompositeOp, but using a continuious mathematical formula rather than two conditionally selected formulae.

PinLightCompositeOp

Similar to HardLightCompositeOp, but using sharp linear shadings, to similate the effects of a strong 'pinhole' light source.

PlusCompositeOp

The result is just the sum of the image data. Output values are cropped to 255 (no overflow). This operation is independent of the matte channels.

ReplaceCompositeOp

The resulting image is image replaced with composite image. Here the matte information is ignored.

SaturateCompositeOp

Each pixel in the result image is the combination of the saturation of the target image and the hue and brightness of the composite image.

ScreenCompositeOp

Multiplies the inverse of each image's color information.

SoftLightCompositeOp

Darkens or lightens the colors, dependent on the source color value. If the source color is lighter than 0.5, the destination is lightened. If the source color is darker than 0.5, the destination is darkened, as if it were burned in. The degree of darkening or lightening is proportional to the difference between the source color and 0.5. If it is equal to 0.5, the destination is unchanged. Painting with pure black or white produces a distinctly darker or lighter area, but does not result in pure black or white.

SrcAtopCompositeOp

The part of the source lying inside of the destination is composited onto the destination.

SrcCompositeOp

The source is copied to the destination. The destination is not used as input.

SrcInCompositeOp

he part of the source lying inside of the destination replaces the destination.

SrcOutCompositeOp

The part of the source lying outside of the destination replaces the destination.

SrcOverCompositeOp

The source is composited over the destination.

SubtractCompositeOp

The result of composite image - image, with underflow wrapping around (mod 256). The add and subtract operators can be used to perform reversable transformations.

ThresholdCompositeOp

?

VividLightCompositeOp

A modified LinearLightCompositeOp designed to preserve very stong primary and secondary colors in the image.

XorCompositeOp

The result is the image data from both composite image and image that is outside the overlap region. The overlap region will be blank.

CompressionType

Express the desired compression type when encoding an image. Be aware that most image types only support a sub-set of the available compression types. If the compression type specified is incompatible with the image, ImageMagick selects a compression type compatible with the image type. See compression.

UndefinedCompression

No compression type has been specified.

NoCompression

The default for most formats.

B44Compression

Available in ImageMagick 6.5.5-4 and later.

B44ACompression

Available in ImageMagick 6.5.5-4 and later.

BZipCompression

BZip (Burrows-Wheeler block-sorting text compression algorithm and Huffman coding) as used by bzip2 utilities

DXT1Compression

Available in ImageMagick 6.3.9-3 and later.

DXT3Compression

Available in ImageMagick 6.3.9-3 and later.

DXT5Compression

Available in ImageMagick 6.3.9-3 and later.

FaxCompression

CCITT Group 3 FAX compression

Group4Compression

CCITT Group 4 FAX compression (used only for TIFF)

JPEGCompression

JPEG compression. See The JPEG image compression FAQ.

JPEG2000Compression

JPEG2000 compression for compressed PDF images.

LosslessJPEGCompression

This compression format is almost never used.

LZWCompression

Lempel-Ziv-Welch (LZW) compression

PizCompression

Available in ImageMagick 6.5.5-4 and later.

Pxr24Compression

Available in ImageMagick 6.5.5-4 and later.

RLECompression

See the Wikipedia page for Run-length encoding.

ZipCompression

Lempel-Ziv compression (LZ77) as used in PKZIP and GNU gzip.

ZipSCompression

Available in ImageMagick 6.5.5-4 and later.

DecorationType

Use with the decorate= method in the Draw class to specify the text decoration for the annotate method.

NoDecoration

Don't decorate the text.

UnderlineDecoration

Underline the text.

OverlineDecoration

Overline the text.

LineThroughDecoration

Draw a horizontal line through the middle of the text.

DisposeType

The value of the dispose attribute.

UndefinedDispose

No disposal specified.

NoneDispose

Do not dispose between frames.

BackgroundDispose

Overwrite the image area with the background color.

PreviousDispose

Overwrite the image area with what was there prior to rendering the image.

DitherMethod

Specify the method of dithering for remap, quantize, posterize, etc.

NoDitherMethod

RiemersmaDitherMethod

FloydSteinbergDitherMethod

EndianType

The value of the endian attribute.

UndefinedEndian

LSBEndian

MSBEndian

FilterTypes

Used to adjust the filter algorithm used when resizing images. Different filters experience varying degrees of success with various images and can take significantly different amounts of processing time. ImageMagick uses the LanczosFilter by default since this filter has been shown to provide the best results for most images in a reasonable amount of time. Other filter types (e.g. TriangleFilter) may execute much faster but may show artifacts when the image is re-sized or around diagonal lines. The only way to be sure is to test the filter with sample images. See resize.

UndefinedFilter

Bartlett

BesselFilter

BlackmanFilter

Bohman

BoxFilter

CatromFilter

CubicFilter

GaussianFilter

HammingFilter

HanningFilter

HermiteFilter

KaiserFilter

LagrangianFilter

LanczosFilter

MitchellFilter

ParzenFilter

PointFilter

QuadraticFilter

SincFilter

TriangleFilter

WelshFilter

GravityType

Specify positioning of an object (e.g. text, image) within a bounding region (e.g. an image). Gravity provides a convenient way to locate objects irrespective of the size of the bounding region, in other words, you don't need to provide absolute coordinates in order to position an object. A common default for gravity is NorthWestGravity. See annotate and composite.

ForgetGravity

Don't use gravity.

NorthWestGravity

Position object at top-left of region

NorthGravity

Position object at top-center of region

NorthEastGravity

Position object at top-right of region

WestGravity

Position object at left-center of region

CenterGravity

Position object at center of region

EastGravity

Position object at right-center of region

SouthWestGravity

Position object at left-bottom of region

SouthGravity

Position object at bottom-center of region

SouthEastGravity

Position object at bottom-right of region

ImageType

Indicate the type classification of the image. See image_type and image_type=.

UndefinedType

No type has been specified.

BilevelType

Monochrome image

GrayscaleType

Grayscale image

PaletteType

Indexed color (palette) image

PaletteMatteType

Indexed color (palette) image with opacity

TrueColorType

Truecolor image

TrueColorMatteType

Truecolor image with opacity

ColorSeparationType

Cyan/Yellow/Magenta/Black (CYMK) image

ColorSeparationMatteType

OptimizeType

PaletteBilevelMatteType

InterlaceType

Specify the ordering of the red, green, and blue pixel information in the image. Interlacing is usually used to make image information available to the user faster by taking advantage of the space vs time tradeoff. For example, interlacing allows images on the Web to be recognizable sooner and satellite images to accumulate/render with image resolution increasing over time. Use LineInterlace or PlaneInterlace to create an interlaced GIF or progressive JPEG image. See interlace.

UndefinedInterlace

No interlace type has been specified.

NoInterlace

Don't interlace image (RGBRGBRGBRGBRGBRGB...)

LineInterlace

Use scanline interlacing (RRR...GGG...BBB...RRR...GGG...BBB...)

PlaneInterlace

Use plane interlacing (RRRRRR...GGGGGG...BBBBBB...)

PartitionInterlace

Similar to plane interlacing except that the different planes are saved to individual files (e.g. image.R, image.G, and image.B)

GIFInterlace

JPEGInterlace

PNGInterlace

See the ImageMagick documentation for the -interlace option.

InterpolatePixelMethod

The pixel color interpolation method. See pixel_interpolation_method.

AverageInterpolatePixel

BicubicInterpolatePixel

BilinearInterpolatePixel

FilterInterpolatePixel

IntegerInterpolatePixel

MeshInterpolatePixel

NearestNeighborInterpolatePixel

SplineInterpolatePixel

For FilterInterpolatePixel, specify the filter with the filter attribute. Specify the sharpness with the blur attribute.

MetricType

The distortion metric type. See compare_channel, distortion_channel.

MeanAbsoluteErrorMetric

MeanSquaredErrorMetric

PeakAbsoluteErrorMetric

PeakSignalToNoiseRatioMetric

RootMeanSquaredErrorMetric

NoiseType

Select the type of noise to be added to the image. See add_noise.

UniformNoise

GaussianNoise

MultiplicativeGaussianNoise

ImpulseNoise

LaplacianNoise

PoissonNoise

RandomNoise

Opacity

represent the maximum and minimum levels of opacity. You can specify a partial level of opacity by choosing a number between OpaqueOpacity and TransparentOpacity. For example, 25% opacity is abs(Magick::TransparentOpacity-Magick::OpaqueOpacity) * 0.25

TransparentOpacity

The minimum amount of opacity.

OpaqueOpacity

The maximum amount of opacity.

OrientationType

Specify the orientation of the image pixels. See Image#orientation and Info#orientation. See http://jpegclub.org/exif_orientation.html for an explanation of these values.

UndefinedOrientation

TopLeftOrientation

TopRightOrientation

BottomRightOrientation

BottomLeftOrientation

LeftTopOrientation

RightTopOrientation

RightBottomOrientation

LeftBottomOrientation

PaintMethod

Specify how pixel colors are to be replaced in the image. See matte_floodfill and texture_floodfill.

PointMethod

Replace pixel color at point.

ReplaceMethod

Replace color for all image pixels matching color at point.

FloodfillMethod

Replace color for pixels surrounding point until encountering pixel that fails to match color at point.

FillToBorderMethod

Replace color for pixels surrounding point until encountering pixels matching border color.

ResetMethod

Replace colors for all pixels in image with fill color.

RenderingIntent

Rendering intent is a concept defined by ICC Spec ICC.1:1998-09, "File Format for Color Profiles". ImageMagick uses RenderingIntent in order to support ICC Color Profiles.

From the specification: "Rendering intent specifies the style of reproduction to be used during the evaluation of this profile in a sequence of profiles. It applies specifically to that profile in the sequence and not to the entire sequence. Typically, the user or application will set the rendering intent dynamically at runtime or embedding time."

See rendering_intent.

UndefinedIntent

No intent has been specified.

SaturationIntent

A rendering intent that specifies the saturation of the pixels in the image is preserved perhaps at the expense of accuracy in hue and lightness.

PerceptualIntent

A rendering intent that specifies the full gamut of the image is compressed or expanded to fill the gamut of the destination device. Gray balance is preserved but colorimetric accuracy might not be preserved.

AbsoluteIntent

Absolute colorimetric

RelativeIntent

Relative colorimetric

ResolutionType

By default, ImageMagick defines resolutions in pixels per inch. ResolutionType provides a means to adjust this. See units.

UndefinedResolution

No resolution has been specified.

PixelsPerInchResolution

Density specifications are specified in units of pixels per inch (English units).

PixelsPerCentimeterResolution

Density specifications are specified in units of pixels per centimeter (metric units).

StretchType

See font_stretch=.

NormalStretch

UltraCondensedStretch

ExtraCondensedStretch

CondensedStretch

SemiCondensedStretch

SemiExpandedStretch

ExpandedStretch

ExtraExpandedStretch

UltraExpandedStretch

AnyStretch

StorageType

See import_pixels and export_pixels_to_str.

CharPixel

corresponds to a C unsigned char, range 0-255.

ShortPixel

corresponds to a C unsigned short, range 0-65535.

IntegerPixel

corresponds to a C unsigned int, range 0-4294967295.

LongPixel

corresponds to a C unsigned long, range 0-4294967295 (for 32-bit longs).

FloatPixel

corresponds to a C float, range 0.0-1.0.

DoublePixel

corresponds to a C double, range 0.0-1.0.

QuantumPixel

corresponds to the Quantum type used by ImageMagick, range 0-QuantumRange.

StyleType

See font_style=.

NormalStyle

ItalicStyle

ObliqueStyle

AnyStyle

WeightType

The font weight can be specified as one of 100, 200, 300, 400, 500, 600, 700, 800, or 900, or one of the following constants. See font_weight=.

AnyWeight

No weight specified.

NormalWeight

Equivalent to 400

BoldWeight

Equivalent to 700

BolderWeight

Increases weight by 100

LighterWeight

Decreases weight by 100