Returns

Example

instance methods

annotate

Description

Annotates a image with text. The text is positioned
according to the gravity attribute around the
rectangle described by the x,
y, width, and
height arguments. If either of the
width or height arguments are 0, uses the image
width-x and the image
height-y to compute the rectangle
width and height. The attributes described in annotate attributes, below, influence the
appearance and position of the text. These attributes may be
set in the Draw object before calling annotate, or
within annotate's optional additional parameters block.

Note: all of the annotate attributes
are set-only.

Arguments

img

the image or imagelist to be annotated

width

width of the rectangle within which the text is
positioned

height

height of the rectangle within which the text is
positioned

x

x offset of the rectangle

y

y offset of the rectangle

text

the text

Returns

self

Example

This example is an excerpt of colors.rb. Many other
examples also use annotate.

Special characters

Escape a blank, quote, or apostrophe by preceding it with a
backslash ("\"). To include a backslash in the text, use two
consecutive backslashes. To include a '%' in the text, use
'%%'. You can include information about the image by including
one or more of the special character sequences shown in this
table.

Special characters

Replaced by

%b

file size in bytes

%c

"comment" property string

%d

directory in which the file resides

%e

filename extension

%f

original filename

%g

group number

%h

height

%i

current filename

%k

number of unique colors

%l

"label" property string

%m

file format

%n

number of images in the sequence (for RMagick, this is
always 1)

%o

output filename

%p

page number (for RMagick, this is always 1)

%q

depth

%r

A string of the form "ClasstypeColorspace," for example
"DirectClassRGB". If the image's matte attribute
is true, appends the word "Matte" to the end
of the string.

Magick API

dup

Description

Returns

See also

get_multiline_type_metrics

draw.get_multiline_type_metrics([image,] string) ->
type_metrics

get_type_metrics

draw.get_type_metrics([image,] string) ->
type_metrics

Description

Returns information for a specific string if rendered on a
image. The get_multiline_type_metrics method is
the same as get_type_metrics, except the former
returns the maximum height and width for multiple lines of
text. (Text lines are separated by "\n" characters.)

The Magick++ documentation for its TypeMetric class provides
this useful additional information. (I've changed it a bit to
use RMagick names.)

The TypeMetric class provides the means to
pass data from the Draw class's get_type_metric method to the
user. It provides information regarding font metrics such as
ascent, descent, text width, text height, and maximum
horizontal advance. The units of these font metrics are in
pixels...(T)he metrics are dependent on the current Image
font (default Ghostscript's "Helvetica"), pointsize (default
12 points), and x/y resolution (default 72 DPI) settings.

The pixel units may be converted to points
(the standard resolution-independent measure used by the
typesetting industry) via the following equation:

size_points = (size_pixels *
72)/resolution

where resolution is in dots-per-inch
(DPI). This means that at the default image resolution, there
is one pixel per point.

Note that a font's pointsize is only a
first-order approximation of the font height (ascender +
descender) in points. The relationship between the specified
pointsize and the rendered font height is determined by the
font designer.

Arguments

image (optional)

The image on which the string will be rendered.
ImageMagick uses the attributes of the image (font name,
pointsize, etc.) to compute the metrics. If this argument is
omitted, get_type_metrics substitutes a dummy
image with default attributes. The string argument may not contain any of the
special characters shown in this table.

string

The string to be rendered. If img is specified, the string may contain special
characters that refer to the image attributes. See this table.

Returns

A TypeMetric struct. This structure has the following
attributes. (The descriptions are taken from the Magick++
documentation and source code.)

TypeMetric attributes

Accessor

Description

ascent

Distance in pixels from the text baseline to the
highest/upper grid coordinate used to place an outline
point. Always a positive value.

descent

Distance in pixels from the baseline to the lowest grid
coordinate used to place an outline point. Always a
negative value.

width

Text width in pixels

height

Text height in pixels

max_advance

Maximum horizontal advance (advance from the beginning
of a character to the beginning of the next character) in
pixels.

Example

This example shows the details of a TypeMetric struct.

This example uses the width and
height values returned by
get_multiline_type_metrics to draw a border around
the text lines.

Magick API

GetTypeMetrics, GetMultilineTypeMetrics

inspect

draw.inspect ->
string

Description

Returns the list of primitives that have been added to the
draw object. This is very handy for debugging.

Returns

Example

See also

bezier

draw.bezier(x1, y1, cx1, cy1, cx2, cy2, x2, y2...) ->
self

Description

Draw a cubic Bezier curve.

Arguments

The arguments are pairs of points. At least 4 pairs must be
specified. Each point xn, yn on the curve is associated with a control point
cxn, cyn. The
first point, x1, y1, is the starting point. The last point,
xn, yn, is
the ending point. Other point/control point pairs specify
intermediate points on a polybezier curve.

Returns

self

Examples

The following examples are taken from the Paths section of the
Scalable Vector Graphics (SVG) 1.1
Specification.

Example 1

gc.bezier(20,120, 20,20, 320,20, 320,120)

Example 2

gc.bezier(25,125, 100,25, 400,25, 325,125)

Example 3

gc.bezier(100,150, 25,50, 475,50, 400,150)

Example 4

gc.bezier(20,180, 20,30, 320,330, 320,180)

Example 5

gc.bezier(20,120, 95,20, 245,20, 320,120)

Example 6

gc.bezier(50,150, 50,50, 200,50, 200,150, 200,250,
350,250, 350,150)

circle

draw.circle(origin_x, origin_y, perim_x, perim_y) ->
self

self

Description

Draw a circle.

Arguments

origin_x, origin_y

The center of the circle.

perim_x, perim_y

A point on the perimeter of the circle.

Returns

self

Example

gc.circle(125,125, 25,125)

clip_path

draw.clip_path(pathname) -> self

Description

Draws the clip path on the image mask. The
clip path defines a clipping area, where only the contained
area will be drawn upon. Areas outside of the clipping area are
masked.

Before using a clip-path, you must create it using the
define_clip_path method. You
must precede clip_path with push and terminate the primitives that draw within
the clip path with pop. For example,

Arguments

Returns

Example

See also

clip_rule

draw.clip_rule("evenodd" or
"nonzero") -> self

Description

Specify how to determine if a point on the image is inside
clipping region. See
the 'fill-rule' property in the
Scalable Vector Graphics (SVG) 1.1 Specification
for a complete description and examples.

Returns

Example 1

Example 2

See also

decorate

Description

Arguments

Returns

self

Example

draw.decorate(LineThroughDecoration)

define_clip_path

draw.define_clip_path(string) { block } ->
self

Description

Define a clip-path. Within block,
call other drawing primitive methods (rectangle,
polygon, text, etc.) to define the
clip-path. The union of all the primitives (excluding the
effects of rendering methods such as stroke_width,
etc.) is the clip-path. After the clip-path is invoked by the
clip-path method, anything drawn on
the image inside the clip-path will appear. Anything drawn
outside the clip-path will be hidden. (See clip_rule for a definition of how ImageMagick
decides what is "inside" and what is "outside" of the
clip-path.)

Arguments

The name of the clip-path. This is the name that is
specified in the clip_path method.

Returns

Example

See also

fill_rule

Description

Specify how to determine if a point on the image is inside a
shape. See
the 'fill-rule' property in the
Scalable Vector Graphics (SVG) 1.1 Specification
for a complete description and examples.

Arguments

Either "evenodd" or "nonzero".

Returns

self

font

draw.font(string) -> self

Description

Specify the font to draw text with.

Arguments

The font name or filename. You can tag
a font to specify whether it is a Postscript, Truetype, or
OPTION1 font. For example, Arial.ttf is a Truetype font,
ps:helvetica is Postscript, and x:fixed is OPTION1.

The font name can be a complete filename such as
"/mnt/windows/windows/fonts/Arial.ttf". The font
name can also be a fully qualified X font name such as
"-urw-times-medium-i-normal--0-0-0-0-p-0-iso8859-13".

Arguments

Returns

Example

See also

interline_spacing

Description

Argument

A numeric value. If positive, inserts additional space
between lines. If negative, removes space between lines. The
amount of space inserted or removed depends on the font.

Returns

self

interword_spacing

draw.interword_spacing(space) -> self

Description

Modify the spacing between words in text.

Argument

A numeric value. If positive, inserts additional space
between words. If negative, removes space between words. The
amount of space inserted or removed depends on the font.

Returns

self

kerning

draw.kerning(space) -> self

Description

Modify the spacing between letters in text.

Argument

A numeric value. If positive, inserts additional space
between letters. If negative, removes space between letters.
The amount of space inserted or removed depends on the font but
is usually measured in pixels. That is, the following call adds
about 5 pixels between each letter.

Make all pixels that are the same color as the pixel
at (x,y) transparent.

FloodfillMethod

Make all the pixels surrounding the pixel at
(x,y) transparent, until encountering pixels
that fail to match color at (x,y).

FillToBorderMethod

Make all the pixels surrounding the pixel at
(x,y) transparent, until encountering pixels
that match the border color. Assign the border color with
the Draw#border_color= attribute before
calling draw.

ResetMethod

Make the entire image transparent.

Returns

self

See also

opacity

draw.opacity(opacity) -> self

Description

Specify the fill and stroke opacities.

Arguments

Either a number between 0 and 1, or a percentage represented
as a string, i.e. "25%". The string argument "25%" is the same
as the numeric argument 0.25. Both the fill and stroke
opacities are set to the specified value.

pop

Description

Returns

See also

push

draw.push -> self

Description

Save the current state of the graphics context, including
the attribute settings and the current set of primitives. Use
the pop primitive to restore the state.

Note: The push and pop
methods are probably not as useful in RMagick as they are in C
language ImageMagick programs, since it is easy to create
separate draw objects, each with its own set of properties and
primitives.

Returns

Aliases

stroke_antialias

Description

stroke_dasharray

draw.stroke_dasharray(x1,...,xn) ->
self

Description

Describe a pattern of dashes to be used when stroking paths.
The arguments are a list of pixel widths of alternating dashes
and gaps.

Arguments

The first argument is the width of the first dash. The
second is the width of the gap following the first dash. The
third argument is another dash width, followed by another gap
width, etc. If you specify an odd number of arguments, the
arguments are repeated to produce an even number. All arguments
must be > 0.

To produce a solid stroke, specify no arguments, i.e.
stroke_dasharray()

Arguments

Returns

Example

See also

stroke_miterlimit

draw.stroke_miterlimit(float) -> self

Description

Specify a constraint on the length of the "miter" formed by
two lines meeting at an angle. If the angle if very sharp, the
miter could be very long relative to the line thickness. The
miter limit is a limit on the ratio of the miter length to the
line width.

Arguments

A number >= 1. The limit on the ratio of the miter length
to the line width.

Returns

self

stroke_opacity

draw.stroke_opacity(float or string) ->
self

Description

Specify the stroke opacity.

Arguments

A number between 0 and 1, inclusive, or a percentage
represented as a string, i.e. '30%'. The argument 0.3 is the
same as '30%'.

Generally it is a good idea to surround the text string with
quotes (""), apostrophes (''), or braces ({}). If the text
string starts with a digit or contains an embedded blank,
quote, or apostrophe, you must do this. ImageMagick removes
these characters before drawing the text. You can also escape a
blank, quote, or apostrophe by preceding it with a backslash
("\"). To include a backslash in the text, use two consecutive
backslashes. To include a '%' in the text, use '%%'. See the
examples below.