RMagick User's Guide and Reference
class Draw

Table Of Contents

class methods

attribute writers

drawing primitive methods

other instance methods

 

class methods

new Magick::Draw.new [ { additional parameters } ] -> draw
Description Creates a new Draw object. You can assign some initial values by setting attributes in the associated block. However, you will usually find it more useful to use one of the Draw instance methods to set these values while the primitives are being executed. When the values are initialized by new, they will be overridden by the corresponding instance method.

The attributes you can set are shown in the following table.

Method Description
antialias=true or false Initializes both stroke_antialias and text_antialias
font=font_name See font
density="XxY" Font density
pointsize=size See pointsize and pointsize=
border_color="color_name"  
server_name="name"  
debug=true or false See draw
Example
primitives = Magick::Draw.new {
   self.font = "Courier"      # override default font
   }
×Magick API CloneDrawInfo

attribute writers

These methods are usually used to set attribute values for the annotate method. They may be set prior to calling annotate or in a block associated with the call. To set a value to be used when drawing with the draw method, use one of the drawing methods listed in the drawing primitive methods section, below.

affine= draw.affine = anAffineMatrix
  The transformation matrix. See AffineMatrix. The default is the null transformation. Also see affine.
align= draw.align = anAlignType
  The text alignment, left, center, or right. The default is LeftAlign. See also text_align.
decorate= draw.decorate = aDecorationType
  The text decoration. See DecorationType. The default is NoDecorationType.
density= draw.density = aString
  The text density in the x and y directions. The default is "72x72".
encoding= draw.encoding = aString
  The text encoding. One of the following strings: "AdobeCustom", "AdobeExpert", "AdobeStandard", "AppleRoman", "BIG5", "GB2312", "Latin 2", "None", "SJISCode", "Symbol", "Unicode", "Wansung".
fill= draw.fill = aString
draw.fill = aPixel
  The name of the fill color. May also be a Pixel object. The default is "black".
font= draw.font = aString
  The font name. The default is "Helvetica". See also font.
font_family= draw.font_family = aString
  The font family name. For example, "arial" or "helvetica".
font_stretch= draw.font_stretch = aStretchType
  A StretchType constant.
font_style= draw.font_style = aStyleType
  A StyleType constant.
font_weight= draw.font_weight = aWeightType
  A WeightType constant or one of the numbers 100, 200, 300, 400, 500, 600, 700, 800, or 900.
gravity= draw.gravity = aGravityType
  The text gravity. The default is NorthWestGravity.
pointsize= draw.pointsize = anInteger
  The font size. The default is 12.
rotation= draw.rotation = aNumber
  Rotate the text. Specify the amount of rotation in degrees.
  See rotated_text.rb.
stroke= draw.stroke = aString
draw.stroke = aPixel
  The stroke color. This is the color used to outline the text. May also be a Pixel object. The default is "black".
text_antialias= draw.text_antialias = true or false
  Whether the text is antialiased or not. The default is true.
undercolor= draw.undercolor = aString
draw.undercolor = aPixel
  If set, causes the text to be drawn over a box of the specified color. May be a color name or a Pixel object. See also text_undercolor.
Example
This example displays the effect of the following attribute values:
      font = "Helvetica"
      decorate = Magick::OverlineDecoration
      fill = "red"
      gravity = Magick::CenterGravity
      pointsize = 48
      stroke = "black"
      undercolor = "cyan"
draw attribute methods example
Notice that, along with the text, the surrounding cyan box is outlined with black, the stroke color. For more examples, see annotate.
 

drawing primitive methods

affine draw.affine(sx, rx, ry, sy, tx, ty) -> draw
Description Transforms the coordinate system by a 3x3 transformation matrix. See Coordinate system transformations in the Scalable Vector Graphics (SVG) 1.0 Specification.
Arguments
sx, sy
The amount of scaling in the x and y directions
rx, ry
The rotation in the x and y directions, in radians.
tx, ty
The translation distances in the x and y directions
Example
draw.affine(1, 0, 0, -1, 0, max_y)
affine example
See also rotate, scale, skewx, skewy, translate
arc draw.arc(start_x, start_y, end_x, end_y, start_degrees, end_degrees) -> draw
Description Draws an arc within a rectangle.
Arguments
start_x, start_y
start point
end_x, end_y
end point
start_degrees, end_degrees
degree of rotation at start and end
Returns self
Example
draw.arc(130,30, 200,100, 45,90)
arc example
Notes This primitive is deprecated. Use the SVG elliptical arc commands (A and a) instead. See path .
bezier draw.bezier(x1,y1, cx1,cy1, cx2,cy2, x2, y2...) -> draw
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.
Example
The following examples are taken from the Paths section of the Scalable Vector Graphics (SVG) 1.0 Specification.
 
draw.bezier(100,200, 100,100, 400, 100, 400,200)
bezier example 1
 
draw.bezier(100,200, 175,100, 475,100, 400,200)
bezier example 2
 
draw.bezier(100,200, 25,100, 475, 100, 400,200)
bezier example 3
 
draw.bezier(100,200, 100,50, 400, 350, 400,200)
bezier example 4
 
draw.bezier(100,200, 175,100, 325, 100, 400,200)
bezier example 5
 
draw.bezier(100,200, 100,100, 250,100, 250,200, 250,300, 400,300, 400,200)
bezier example 6
circle draw.circle(origin_x, origin_y, perim_x, perim_y) -> draw
Description Draw a circle centered on the point origin_x, origin_y and the point perim_x, perim_y on the perimeter.
Example
draw.circle(125,125, 25,125)
circle example
clip_path draw.clip_path(pathname) -> draw
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.

Arguments The name of the clip path.
Example
draw.clip_path('example')
clip_path example
See also define_clip_path
clip_rule draw.clip_rule("evenodd" or "nonzero") -> draw
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.0 Specification for a complete description and examples.
Arguments Either "evenodd" or "nonzero".
clip_units draw.clip_units("userSpace" or "userSpaceOnUse" or "objectSpace") -> draw
Description Defines the coordinate space within the clipping region. See the clipPathUnits property in the Scalable Vector Graphics (SVG) 1.0 Specification for a complete description and examples.
Arguments Either "userSpace", "userSpaceOnUse", or "objectSpace".
color draw.color(x, y, aPaintMethod) -> draw
Description Set color in image according to the specified PaintMethod constant.
Arguments See the PaintMethod constants.
Example draw.color(x, y, Magick::ReplaceMethod)
composite draw.composite(x, y, width, height, composite_image, op=Magick::OverCompositeOp) -> draw
Description Composite composite_image with the background image.
Arguments
x, y
The offset of composite_image relative to the background image.
width, height
Scale the composite_image to this size. If either value is 0, composite_image is not scaled.
composite_image
Either an imagelist or a image. If an imagelist, uses the current image.
op
A CompositeOperator constant.
Examples
composite example 1 composite example 2
See also Image#composite
decorate draw.decorate(aDecorationType) -> draw
Description Specify text decoration.
Arguments See the DecorationType constants.
Example draw.decorate(Magick::LineThroughDecoration)
See also decorate=
define_clip_path draw.define_clip_path(aString) { block } -> draw
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 ×Magick decides what is "inside" and what is "outside" of the clip-path.)
Arguments The name of the clip-path.
Example See the example for clip_path.
See also clip_path
ellipse draw.ellipse(origin_x, origin_y, width, height, arc_start, arc_end) -> draw
Description Draw an ellipse.
Arguments
origin_x, origin_y
The center of the ellipse
width, height
The horizontal and vertical radii
arc_start
Where to start the ellipse, in degrees. 0 degrees is at 3 o'clock.
arc_end
Where to end the ellipse, in degrees
Example
draw.ellipse(180,125, 150,75, 0, 270)
ellipse example
encoding draw.encoding("UTF-8") -> draw
Description Specify the font encoding as "UTF-8".
Arguments "UTF-8". (Note: This looks like a placeholder in ×Magick. All other arguments are ignored.)
See also encoding=
fill draw.fill(aString) -> draw
Description Specify the color or pattern with which graphical elements are filled.
Arguments A color name or pattern name.
Example draw.fill('red')
Aliases fill_color, fill_pattern
fill_opacity draw.fill_opacity(aFloat) -> draw
draw.fill_opacity(aString -> draw)
Description Specify the fill opacity.
Arguments A number between 0 and 1, inclusive, or a percentage represented as a string, i.e. '30%'. The argument .3 is the same as '30%'.
Example
draw.fill_opacity(.4)
draw.fill_opacity('40%')

See the example for opacity.

See also opacity
stroke_opacity
fill_rule draw.fill_rule("evenodd" or "nonzero") -> draw
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.0 Specification for a complete description and examples.
Arguments Either "evenodd" or "nonzero".
font draw.font(aString) -> draw
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".

Example draw.font('Helvetica')
font_family draw.font_family(aString) -> draw
Description Specify the font family.
Arguments A font family name such as "arial" or "helvetica".
Example See the example for text.
font_stretch draw.font_stretch(aStretchType) -> draw
Description Specify the spacing between text characters.
Arguments A StretchType constant.
Example draw.font_stretch(Magick::UltraCondensedStretch)
font_style draw.font_style(aStyleType) -> draw
Description Specify the font style, i.e. italic, oblique, or normal.
Arguments A StyleType constant.
Example See the example for text.
font_weight draw.font_weight(aWeightType) -> draw
Description Specify the font weight. For example, "bold" or "normal".
Arguments A WeightType constant, or one of the numbers 100, 200, 300, 400, 500, 600, 700, 800, or 900.
Example See the example for text.
gravity draw.gravity(aGravityType) -> draw
Description Specify how the text is positioned. The default is Magick::NorthWestGravity.
Arguments A GravityType constant.
Example gravity example
See also text
line draw.line(here_x, here_y, there_x, there_y) -> draw
Description Draw a line from here to there.
Arguments
here_x, here_y
The starting point.
there_x, there_y
The ending point.
Example
draw.line(50,50, 50,200)
draw.line(50,200, 200,200)
draw.line(200,200, 50,50)
line example
matte draw.matte(x,y, aPaintMethod) -> draw
Description Make the image transparent according to the specified PaintMethod constant.
Arguments
x, y
Point in image to use, along with the PaintMethod constant, to set transparent pixels in the image.
aPaintMethod
One of the following PaintMethod constants:
PointMethod
Make the pixel at (x,y) transparent.
ReplaceMethod
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.
ResetMethod
Make the entire image transparent.
See also Image#matte_point, Image#matte_replace, Image#matte_floodfill, Image#matte_fill_to_border, Image#opaque, Image#transparent
opacity draw.opacity(opacity) -> draw
Description Specify the fill and stroke opacities.
Argument 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.
Example opacity example
See also fill_opacity
stroke_opacity
path draw.path(aString)
Description Draw using SVG-compatible path drawing commands. See "Paths" in the Scalable Vector Graphics (SVG) 1.0 Specification.
Arguments A string containing SVG moveto, line, curve, arc, or closepath instructions. The string is equivalent to the d attribute in an SVG 'path' element.
Example These examples are all taken from the SVG path examples.
Example arcs01
path example 1
Example quad01
path example 2
Example cubic01
path example 3
pattern draw.pattern(name, x, y, width, height) { pattern primitives } -> draw
Description Define a pattern that can be used as the fill or stroke pattern.
Arguments
name
The name of the pattern. The pattern is used in a fill or stroke method by specifying its name.
x, y, width, height
Define how the pattern is tiled. The pattern rectangles start at (x + m*width, y+n*height) for the values of n and m as necessary to fill the space.
pattern primitives
The method calls that draw the pattern.
Example
pattern example 1 pattern example 2
See also fill, stroke
point draw.point(x, y) -> draw
Description Set the pixel at x,y to the fill color.
Arguments
x, y
The pixel location
Example draw.point(30, 40)
pointsize draw.pointsize(anInteger) -> draw
Description Set the font size in points. The default is 12.
Example See the example for text.
Alias font_size
polygon draw.polygon(x1, y1,...,xN, yN) -> draw
Description Draw a polygon.
Arguments The arguments are a sequence of 2 or more points. If the last point is not the same as the first, the polygon is closed by drawing a line from the last point to the first.
Example
This example is taken from the The 'polygon' element in the Scalable Vector Graphics (SVG) 1.0 Specification
polygon example
polyline draw.polyline(x1, y1,...,xN, yN) -> draw
Description Draw a polyline. Unlike a polygon, a polyline is not automatically closed.
Arguments A sequence of 2 or more points.
Example
This example is taken from the The 'polyline' element in the Scalable Vector Graphics (SVG) 1.0 Specification
polyline example
pop draw.pop -> draw
Description Restore the graphics context to its previous state.
Example draw.pop
See also push
push draw.push -> draw
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 primitives are probably not as useful in RMagick as they are in C language ×Magick programs, since it is easy to create separate draw objects, each with its own set of properties and primitives.

Example draw.push
See also pop
rectangle draw.rectangle(x1, y1, x2, y2) -> draw
Description Draw a rectangle.
Arguments
x1, y1
The upper left hand corner of the rectangle
x2, y2
The lower right hand corner of the rectangle
Example
draw.rectangle(20,20, 280,180)
rectangle example
rotate draw.rotate(degrees) -> draw
Description Specify a rotation transformation to the coordinate space. The default is 0.
Arguments The amount of rotation, in degrees. The angle of rotation is clockwise, so 90° is south.
Example
draw.rotate(45)
rotate example
See also affine
roundrectangle draw.roundrectangle(x1, y1, x2, y2, cw, ch) -> draw
Description Draw a rectangle with rounded corners.
Arguments
x1, y1
The upper left hand corner of the rectangle
x2, y2
The lower right hand corner of the rectangle
cw, ch
The corner width and height
Example
draw.roundrectangle(20,20, 280,180, 8, 8)
roundrectangle example
scale draw.scale(sx, sy) -> draw
Description Define a scale transformation to the coordinate space. The default scale is (1.0, 1,0).
Arguments
sx, sy
The amount of scaling in the x and y dimensions.
Example
draw.scale(1.5, 1.25)
scale example
See also affine
skewx
skewy
skewx draw.skewx(aFloat) -> draw
Description Define a skew tranformation along the x-axis.
Arguments The amount of skew, in degrees.
Example
draw.skewx(30)
skewx example
See also skewy, rotate
skewy draw.skewy(aFloat) -> draw
Description Define a skew tranformation along the y-axis.
Arguments The amount of skew, in degrees.
Example
draw.skewy(30)
skewy example
See also skewx, rotate
stroke draw.stroke(aString) -> draw
Description Specify the stroke color or pattern.
Arguments A color name or pattern name.
Example draw.stroke('red')
Aliases stroke_color, stroke_pattern
stroke_antialias draw.stroke_antialias(true or false) -> draw
Description Specify if stroke should be antialiased. The default is true.
Example draw.stroke_antialias(false)
stroke_dasharray draw.stroke_dasharray(x1,...,xn) -> draw
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()

Example stroke_dasharray example
See also stroke_dashoffset
stroke_dashoffset draw.stroke_dashoffset(anInteger) -> draw
Description Specify the initial distance into the dash pattern.
Arguments The initial distance into the dash pattern. The units are pixels.
Example See stroke_dasharray.
See also stroke_dasharray
stroke_linecap draw.stroke_linecap(aString) -> draw
Description Specify how the line ends should be drawn.
Arguments One of "butt", "round", or "square".
Example
The following example is from the Stroke Properties section of the Scalable Vector Graphics (SVG) 1.0 Specification.
stroke_linecap example
stroke_linejoin draw.stroke_linejoin(aString) -> draw
Description Specify how corners are drawn.
Arguments One of "miter", "round", or "bevel".
Example
The following example is from the Stroke Properties section of the Scalable Vector Graphics (SVG) 1.0 Specification.
stroke_linejoin example
stroke_miterlimit draw.stroke_miterlimit(aFloat) -> draw
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.
Example draw.stroke_miterlimit(2.0)
stroke_opacity draw.stroke_opacity(aFloat) -> draw
draw.stroke_opacity(aString) -> draw
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 .3 is the same as '30%'.
Example
draw.stroke_opacity(.4)
draw.stroke_opacity('40%')

See the example for opacity.

See also opacity
fill_opacity
stroke_width draw.stroke_width(anInteger) -> draw
Description Specify the stroke width in pixels.
Example stroke_width example
text draw.text(x,y, text) -> draw
Description Draw text at the location specified by (x,y). Use gravity to position the text relative to (x, y). Specify the text appearance with the font, font_family, font_stretch, font_style, and font_weight methods. Use the text_antialias method to set antialiasing on or off.
Arguments
x, y
The text position.
text
The text.
Example text example
See also annotate
text_align draw.text_align(anAlignType) -> draw
Description Align text relative to the starting point.
Arguments An AlignType constant.
Example text_align example
text_anchor draw.text_anchor(anAnchorType) -> draw
Description Align text relative to the starting point. This is the SVG 1.1 equivalent to text_align.
Arguments One of the constants Magick::AnchorStart, Magick::AnchorMiddle, or Magick::AnchorEnd.
text_antialias draw.antialias(true or false) -> draw
Description Specify if the text is to be antialiased.
Arguments Either true or false. The default is true.
Example
The character on the left is not antialiased. The character on the right is antialiased.
text_antialias example
text_undercolor draw.undercolor(aString) -> draw
Description The color to draw underneath text. The default is transparent.
Arguments A color name.
Example text_undercolor example
translate draw.translate(tx, ty) -> draw
Description Specify a translation operation on the coordinate space.
Arguments
tx, ty
The amount of translation in the x and y directions.
Example translate example
See also affine

other instance methods

annotate draw.annotate(img, width, height, x, y, text) [ { additional parameters } ] -> draw
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 omitted, uses the image width - x and the image height - y to compute the rectangle width and height. The attributes described in attribute writers, above, influence the appearance and position of the text. These attributes may be set within the optional additional parameters block.
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 See attribute writers, also gravity.rb
×Magick API AnnotateImage
Advanced You can include information about the image by including one or more of the special characters shown in this table.
Special characters
%b the file size in bytes
%c comment
%d the directory in which the image file resides
%e the image filename extension
%f original image filename
%h image height
%i current image filename
%k number of unique colors
%l the label string
%m the image file format
%n number of images in the image sequence (for RMagick, this is always 1)
%o output image filename
%p image page number
%q image depth
%s scene number (within a sequence, not to be confused with the Image#scene attribute)
%t image filename without extension
%u unique temporary filename
%w image widith
%x x resolution
%y y resolution
draw draw.draw(img) -> draw
Description Draws the list of graphic primitives on the specified image.
Arguments Either an imagelist or a image. If an imagelist, draws on the current image.
Example See the other examples for the Draw class.
×Magick API DrawImage
Notes Calling draw does not affect the list of primitives. Each time you call draw the primitives will be re-executed from the beginning. However, if you establish the initial value of some draw object attributes using the optional parameters to new, or by setting one or more attributes, keep in mind that the initial state will not be restored after draw completes. If you want to use the draw object again, you must reset the attributes yourself.
get_type_metrics draw.get_type_metrics([anImage,] aString) -> aTypeMetric
Description Returns information for a specific string if rendered on a image.
Arguments
image (optional)
The image on which the string will be rendered. ×Magick 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 the table above.
string
The string to be rendered. If image is specified, the string may contain special characters that refer to the image attributes. See the table above.
Returns A Magick::TypeMetric struct. This structure has the following attributes. (The descriptions are taken from the Magick++ documentation and source code.)
Accessor Description
pixels_per_em.x Character width. (See Point.)
pixels_per_em.y Character height
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.
bounds.x1  
bounds.x2  
bounds.y1  
bounds.y1  
underline_position  
underline_thickness  
×Magick API GetTypeMetrics
Advanced 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.

See FreeType Glyph Conventions for a detailed description of font metrics related issues.

inspect draw.inspect -> draw
Description Displays the list of primitives that have been added to the draw object.
Example
draw.inspect »
   "stroke red
    fill transparent
    rectangle 20,20 380,180
    line 200,20 200,180
    line 20,100 380,100
    stroke transparent
    fill black"