class Magick::Draw


Constants

ALIGN_TYPE_NAMES

Thse hashes are used to map Magick constant values to the strings used in the primitives.

ANCHOR_TYPE_NAMES
DECORATION_TYPE_NAMES
FONT_WEIGHT_NAMES
GRAVITY_NAMES
PAINT_METHOD_NAMES
STRETCH_TYPE_NAMES
STYLE_TYPE_NAMES

Public Instance Methods

affine(sx, rx, ry, sy, tx, ty) click to toggle source

Apply coordinate transformations to support scaling (s), rotation ®, and translation (t). Angles are specified in radians.

# File lib/rmagick_internal.rb, line 255
def affine(sx, rx, ry, sy, tx, ty)
  primitive 'affine ' + sprintf('%g,%g,%g,%g,%g,%g', sx, rx, ry, sy, tx, ty)
end
alpha(x, y, method) click to toggle source

Set alpha (make transparent) in image according to the specified colorization rule

# File lib/rmagick_internal.rb, line 261
def alpha(x, y, method)
  Kernel.raise ArgumentError, 'Unknown paint method' unless PAINT_METHOD_NAMES.key?(method.to_i)
  name = Gem::Version.new(Magick::IMAGEMAGICK_VERSION) > Gem::Version.new('7.0.0') ? 'alpha ' : 'matte '
  primitive name + sprintf('%g,%g, %s', x, y, PAINT_METHOD_NAMES[method.to_i])
end
arc(start_x, start_y, end_x, end_y, start_degrees, end_degrees) click to toggle source

Draw an arc.

# File lib/rmagick_internal.rb, line 268
def arc(start_x, start_y, end_x, end_y, start_degrees, end_degrees)
  primitive 'arc ' + sprintf(
    '%g,%g %g,%g %g,%g',
    start_x, start_y, end_x, end_y, start_degrees, end_degrees
  )
end
bezier(*points) click to toggle source

Draw a bezier curve.

# File lib/rmagick_internal.rb, line 276
def bezier(*points)
  if points.empty?
    Kernel.raise ArgumentError, 'no points specified'
  elsif points.length.odd?
    Kernel.raise ArgumentError, 'odd number of arguments specified'
  end
  primitive 'bezier ' + points.map! { |x| sprintf('%g', x) }.join(',')
end
circle(origin_x, origin_y, perim_x, perim_y) click to toggle source

Draw a circle

# File lib/rmagick_internal.rb, line 286
def circle(origin_x, origin_y, perim_x, perim_y)
  primitive 'circle ' + sprintf('%g,%g %g,%g', origin_x, origin_y, perim_x, perim_y)
end
clip_path(name) click to toggle source

Invoke a clip-path defined by def_clip_path.

# File lib/rmagick_internal.rb, line 291
def clip_path(name)
  primitive "clip-path #{to_string(name)}"
end
clip_rule(rule) click to toggle source

Define the clipping rule.

# File lib/rmagick_internal.rb, line 296
def clip_rule(rule)
  rule = to_string(rule)
  Kernel.raise ArgumentError, "Unknown clipping rule #{rule}" unless %w[evenodd nonzero].include?(rule.downcase)
  primitive "clip-rule #{rule}"
end
clip_units(unit) click to toggle source

Define the clip units

# File lib/rmagick_internal.rb, line 303
def clip_units(unit)
  unit = to_string(unit)
  Kernel.raise ArgumentError, "Unknown clip unit #{unit}" unless %w[userspace userspaceonuse objectboundingbox].include?(unit.downcase)
  primitive "clip-units #{unit}"
end
color(x, y, method) click to toggle source

Set color in image according to specified colorization rule. Rule is one of point, replace, floodfill, filltoborder,reset

# File lib/rmagick_internal.rb, line 311
def color(x, y, method)
  Kernel.raise ArgumentError, "Unknown PaintMethod: #{method}" unless PAINT_METHOD_NAMES.key?(method.to_i)
  primitive 'color ' + sprintf('%g,%g,%s', x, y, PAINT_METHOD_NAMES[method.to_i])
end
decorate(decoration) click to toggle source

Specify EITHER the text decoration (none, underline, overline, line-through) OR the text solid background color (any color name or spec)

# File lib/rmagick_internal.rb, line 318
def decorate(decoration)
  if DECORATION_TYPE_NAMES.key?(decoration.to_i)
    primitive "decorate #{DECORATION_TYPE_NAMES[decoration.to_i]}"
  else
    primitive "decorate #{enquote(decoration)}"
  end
end
define_clip_path(name) { || ... } click to toggle source

Define a clip-path. A clip-path is a sequence of primitives bracketed by the “push clip-path <name>” and “pop clip-path” primitives. Upon advice from the IM guys, we also bracket the clip-path primitives with “push(pop) defs” and “push (pop) graphic-context”.

# File lib/rmagick_internal.rb, line 331
def define_clip_path(name)
  push('defs')
  push("clip-path #{enquote(name)}")
  push('graphic-context')
  yield
ensure
  pop('graphic-context')
  pop('clip-path')
  pop('defs')
end
ellipse(origin_x, origin_y, width, height, arc_start, arc_end) click to toggle source

Draw an ellipse

# File lib/rmagick_internal.rb, line 343
def ellipse(origin_x, origin_y, width, height, arc_start, arc_end)
  primitive 'ellipse ' + sprintf(
    '%g,%g %g,%g %g,%g',
    origin_x, origin_y, width, height, arc_start, arc_end
  )
end
encoding(encoding) click to toggle source

Let anything through, but the only defined argument is “UTF-8”. All others are apparently ignored.

# File lib/rmagick_internal.rb, line 352
def encoding(encoding)
  primitive "encoding #{to_string(encoding)}"
end
fill(colorspec) click to toggle source

Specify object fill, a color name or pattern name

# File lib/rmagick_internal.rb, line 357
def fill(colorspec)
  primitive "fill #{enquote(colorspec)}"
end
Also aliased as: fill_color, fill_pattern
fill_color(colorspec)
Alias for: fill
fill_opacity(opacity) click to toggle source

Specify fill opacity (use “xx%” to indicate percentage)

# File lib/rmagick_internal.rb, line 364
def fill_opacity(opacity)
  opacity = to_opacity(opacity)
  primitive "fill-opacity #{opacity}"
end
fill_pattern(colorspec)
Alias for: fill
fill_rule(rule) click to toggle source
# File lib/rmagick_internal.rb, line 369
def fill_rule(rule)
  rule = to_string(rule)
  Kernel.raise ArgumentError, "Unknown fill rule #{rule}" unless %w[evenodd nonzero].include?(rule.downcase)
  primitive "fill-rule #{rule}"
end
font(name) click to toggle source

Specify text drawing font

# File lib/rmagick_internal.rb, line 376
def font(name)
  primitive "font #{enquote(name)}"
end
font_family(name) click to toggle source
# File lib/rmagick_internal.rb, line 380
def font_family(name)
  primitive "font-family #{enquote(name)}"
end
font_size(points)
Alias for: pointsize
font_stretch(stretch) click to toggle source
# File lib/rmagick_internal.rb, line 384
def font_stretch(stretch)
  Kernel.raise ArgumentError, 'Unknown stretch type' unless STRETCH_TYPE_NAMES.key?(stretch.to_i)
  primitive "font-stretch #{STRETCH_TYPE_NAMES[stretch.to_i]}"
end
font_style(style) click to toggle source
# File lib/rmagick_internal.rb, line 389
def font_style(style)
  Kernel.raise ArgumentError, 'Unknown style type' unless STYLE_TYPE_NAMES.key?(style.to_i)
  primitive "font-style #{STYLE_TYPE_NAMES[style.to_i]}"
end
font_weight(weight) click to toggle source

The font weight argument can be either a font weight constant or [100,200,…,900]

# File lib/rmagick_internal.rb, line 396
def font_weight(weight)
  if weight.is_a?(WeightType)
    primitive "font-weight #{FONT_WEIGHT_NAMES[weight.to_i]}"
  else
    primitive "font-weight #{Integer(weight)}"
  end
end
gravity(grav) click to toggle source

Specify the text positioning gravity, one of: NorthWest, North, NorthEast, West, Center, East, SouthWest, South, SouthEast

# File lib/rmagick_internal.rb, line 406
def gravity(grav)
  Kernel.raise ArgumentError, 'Unknown text positioning gravity' unless GRAVITY_NAMES.key?(grav.to_i)
  primitive "gravity #{GRAVITY_NAMES[grav.to_i]}"
end
image(composite, x, y, width, height, image_file_path) click to toggle source
# File lib/rmagick_internal.rb, line 411
def image(composite, x, y, width, height, image_file_path)
  Kernel.raise ArgumentError, 'Unknown composite' unless composite.is_a?(CompositeOperator)
  composite_name = composite.to_s.sub!('CompositeOp', '')
  primitive 'image ' + sprintf('%s %g,%g %g,%g %s', composite_name, x, y, width, height, enquote(image_file_path))
end
interline_spacing(space) click to toggle source

IM 6.5.5-8 and later

# File lib/rmagick_internal.rb, line 418
def interline_spacing(space)
  primitive "interline-spacing #{Float(space)}"
end
interword_spacing(space) click to toggle source

IM 6.4.8-3 and later

# File lib/rmagick_internal.rb, line 423
def interword_spacing(space)
  primitive "interword-spacing #{Float(space)}"
end
kerning(space) click to toggle source

IM 6.4.8-3 and later

# File lib/rmagick_internal.rb, line 428
def kerning(space)
  primitive "kerning #{Float(space)}"
end
line(start_x, start_y, end_x, end_y) click to toggle source

Draw a line

# File lib/rmagick_internal.rb, line 433
def line(start_x, start_y, end_x, end_y)
  primitive 'line ' + sprintf('%g,%g %g,%g', start_x, start_y, end_x, end_y)
end
opacity(opacity) click to toggle source

Specify drawing fill and stroke opacities. If the value is a string ending with a %, the number will be multiplied by 0.01.

# File lib/rmagick_internal.rb, line 439
def opacity(opacity)
  opacity = to_opacity(opacity)
  primitive "opacity #{opacity}"
end
path(cmds) click to toggle source

Draw using SVG-compatible path drawing commands. Note that the primitive requires that the commands be surrounded by quotes or apostrophes. Here we simply use apostrophes.

# File lib/rmagick_internal.rb, line 447
def path(cmds)
  primitive "path #{enquote(cmds)}"
end
pattern(name, x, y, width, height) { || ... } click to toggle source

Define a pattern. In the block, call primitive methods to draw the pattern. Reference the pattern by using its name as the argument to the ‘fill’ or ‘stroke’ methods

# File lib/rmagick_internal.rb, line 454
def pattern(name, x, y, width, height)
  push('defs')
  push("pattern #{to_string(name)} " + sprintf('%g %g %g %g', x, y, width, height))
  push('graphic-context')
  yield
ensure
  pop('graphic-context')
  pop('pattern')
  pop('defs')
end
point(x, y) click to toggle source

Set point to fill color.

# File lib/rmagick_internal.rb, line 466
def point(x, y)
  primitive 'point ' + sprintf('%g,%g', x, y)
end
pointsize(points) click to toggle source

Specify the font size in points. Yes, the primitive is “font-size” but in other places this value is called the “pointsize”. Give it both names.

# File lib/rmagick_internal.rb, line 472
def pointsize(points)
  primitive 'font-size ' + sprintf('%g', points)
end
Also aliased as: font_size
polygon(*points) click to toggle source

Draw a polygon

# File lib/rmagick_internal.rb, line 478
def polygon(*points)
  if points.empty?
    Kernel.raise ArgumentError, 'no points specified'
  elsif points.length.odd?
    Kernel.raise ArgumentError, 'odd number of points specified'
  end
  primitive 'polygon ' + points.map! { |x| sprintf('%g', x) }.join(',')
end
polyline(*points) click to toggle source

Draw a polyline

# File lib/rmagick_internal.rb, line 488
def polyline(*points)
  if points.empty?
    Kernel.raise ArgumentError, 'no points specified'
  elsif points.length.odd?
    Kernel.raise ArgumentError, 'odd number of points specified'
  end
  primitive 'polyline ' + points.map! { |x| sprintf('%g', x) }.join(',')
end
pop(*what) click to toggle source

Return to the previously-saved set of whatever pop(‘graphic-context’) (the default if no arguments) pop(‘defs’) pop(‘gradient’) pop(‘pattern’)

# File lib/rmagick_internal.rb, line 503
def pop(*what)
  if what.empty?
    primitive 'pop graphic-context'
  else
    primitive 'pop ' + what.map { |x| to_string(x) }.join(' ')
  end
end
push(*what) click to toggle source

Push the current set of drawing options. Also you can use push(‘graphic-context’) (the default if no arguments) push(‘defs’) push(‘gradient’) push(‘pattern’)

# File lib/rmagick_internal.rb, line 516
def push(*what)
  if what.empty?
    primitive 'push graphic-context'
  else
    primitive 'push ' + what.map { |x| to_string(x) }.join(' ')
  end
end
rectangle(upper_left_x, upper_left_y, lower_right_x, lower_right_y) click to toggle source

Draw a rectangle

# File lib/rmagick_internal.rb, line 525
def rectangle(upper_left_x, upper_left_y, lower_right_x, lower_right_y)
  primitive 'rectangle ' + sprintf(
    '%g,%g %g,%g',
    upper_left_x, upper_left_y, lower_right_x, lower_right_y
  )
end
rotate(angle) click to toggle source

Specify coordinate space rotation. “angle” is measured in degrees

# File lib/rmagick_internal.rb, line 533
def rotate(angle)
  primitive 'rotate ' + sprintf('%g', angle)
end
roundrectangle(center_x, center_y, width, height, corner_width, corner_height) click to toggle source

Draw a rectangle with rounded corners

# File lib/rmagick_internal.rb, line 538
def roundrectangle(center_x, center_y, width, height, corner_width, corner_height)
  primitive 'roundrectangle ' + sprintf(
    '%g,%g,%g,%g,%g,%g',
    center_x, center_y, width, height, corner_width, corner_height
  )
end
scale(x, y) click to toggle source

Specify scaling to be applied to coordinate space on subsequent drawing commands.

# File lib/rmagick_internal.rb, line 546
def scale(x, y)
  primitive 'scale ' + sprintf('%g,%g', x, y)
end
skewx(angle) click to toggle source
# File lib/rmagick_internal.rb, line 550
def skewx(angle)
  primitive 'skewX ' + sprintf('%g', angle)
end
skewy(angle) click to toggle source
# File lib/rmagick_internal.rb, line 554
def skewy(angle)
  primitive 'skewY ' + sprintf('%g', angle)
end
stroke(colorspec) click to toggle source

Specify the object stroke, a color name or pattern name.

# File lib/rmagick_internal.rb, line 559
def stroke(colorspec)
  primitive "stroke #{enquote(colorspec)}"
end
Also aliased as: stroke_color, stroke_pattern
stroke_antialias(bool) click to toggle source

Specify if stroke should be antialiased or not

# File lib/rmagick_internal.rb, line 566
def stroke_antialias(bool)
  bool = bool ? '1' : '0'
  primitive "stroke-antialias #{bool}"
end
stroke_color(colorspec)
Alias for: stroke
stroke_dasharray(*list) click to toggle source

Specify a stroke dash pattern

# File lib/rmagick_internal.rb, line 572
def stroke_dasharray(*list)
  if list.empty?
    primitive 'stroke-dasharray none'
  else
    list.map! { |x| Float(x) }.each do |x|
      Kernel.raise ArgumentError, "dash array elements must be > 0 (#{x} given)" if x <= 0
    end
    primitive "stroke-dasharray #{list.join(',')}"
  end
end
stroke_dashoffset(value = 0) click to toggle source

Specify the initial offset in the dash pattern

# File lib/rmagick_internal.rb, line 584
def stroke_dashoffset(value = 0)
  primitive 'stroke-dashoffset ' + sprintf('%g', value)
end
stroke_linecap(value) click to toggle source
# File lib/rmagick_internal.rb, line 588
def stroke_linecap(value)
  value = to_string(value)
  Kernel.raise ArgumentError, "Unknown linecap type: #{value}" unless %w[butt round square].include?(value.downcase)
  primitive "stroke-linecap #{value}"
end
stroke_linejoin(value) click to toggle source
# File lib/rmagick_internal.rb, line 594
def stroke_linejoin(value)
  value = to_string(value)
  Kernel.raise ArgumentError, "Unknown linejoin type: #{value}" unless %w[round miter bevel].include?(value.downcase)
  primitive "stroke-linejoin #{value}"
end
stroke_miterlimit(value) click to toggle source
# File lib/rmagick_internal.rb, line 600
def stroke_miterlimit(value)
  value = Float(value)
  Kernel.raise ArgumentError, 'miterlimit must be >= 1' if value < 1
  primitive "stroke-miterlimit #{value}"
end
stroke_opacity(opacity) click to toggle source

Specify opacity of stroke drawing color

(use "xx%" to indicate percentage)
# File lib/rmagick_internal.rb, line 608
def stroke_opacity(opacity)
  opacity = to_opacity(opacity)
  primitive "stroke-opacity #{opacity}"
end
stroke_pattern(colorspec)
Alias for: stroke
stroke_width(pixels) click to toggle source

Specify stroke (outline) width in pixels.

# File lib/rmagick_internal.rb, line 614
def stroke_width(pixels)
  primitive 'stroke-width ' + sprintf('%g', pixels)
end
text(x, y, text) click to toggle source

Draw text at position x,y. Add quotes to text that is not already quoted.

# File lib/rmagick_internal.rb, line 619
def text(x, y, text)
  text = to_string(text)
  Kernel.raise ArgumentError, 'missing text argument' if text.empty?
  if text.length > 2 && /\A(?:"[^\"]+"|'[^\']+'|\{[^\}]+\})\z/.match(text)
  # text already quoted
  elsif !text['\'']
    text = '\'' + text + '\''
  elsif !text['"']
    text = '"' + text + '"'
  elsif !(text['{'] || text['}'])
    text = '{' + text + '}'
  else
    # escape existing braces, surround with braces
    text = '{' + text.gsub(/[}]/) { |b| '\\' + b } + '}'
  end
  primitive 'text ' + sprintf('%g,%g %s', x, y, text)
end
text_align(alignment) click to toggle source

Specify text alignment relative to a given point

# File lib/rmagick_internal.rb, line 638
def text_align(alignment)
  Kernel.raise ArgumentError, "Unknown alignment constant: #{alignment}" unless ALIGN_TYPE_NAMES.key?(alignment.to_i)
  primitive "text-align #{ALIGN_TYPE_NAMES[alignment.to_i]}"
end
text_anchor(anchor) click to toggle source

SVG-compatible version of text_align

# File lib/rmagick_internal.rb, line 644
def text_anchor(anchor)
  Kernel.raise ArgumentError, "Unknown anchor constant: #{anchor}" unless ANCHOR_TYPE_NAMES.key?(anchor.to_i)
  primitive "text-anchor #{ANCHOR_TYPE_NAMES[anchor.to_i]}"
end
text_antialias(boolean) click to toggle source

Specify if rendered text is to be antialiased.

# File lib/rmagick_internal.rb, line 650
def text_antialias(boolean)
  boolean = boolean ? '1' : '0'
  primitive "text-antialias #{boolean}"
end
text_undercolor(color) click to toggle source

Specify color underneath text

# File lib/rmagick_internal.rb, line 656
def text_undercolor(color)
  primitive "text-undercolor #{enquote(color)}"
end
translate(x, y) click to toggle source

Specify center of coordinate space to use for subsequent drawing commands.

# File lib/rmagick_internal.rb, line 662
def translate(x, y)
  primitive 'translate ' + sprintf('%g,%g', x, y)
end

Private Instance Methods

enquote(str) click to toggle source
# File lib/rmagick_internal.rb, line 225
def enquote(str)
  str = to_string(str)
  if str.length > 2 && /\A(?:"[^\"]+"|'[^\']+'|\{[^\}]+\})\z/.match(str)
    str
  else
    '"' + str + '"'
  end
end
to_opacity(opacity) click to toggle source
# File lib/rmagick_internal.rb, line 234
def to_opacity(opacity)
  return opacity if opacity.is_a?(String) && opacity.end_with?('%')

  value = Float(opacity)
  Kernel.raise ArgumentError, 'opacity must be >= 0 and <= 1.0' if value < 0 || value > 1.0

  value
end
to_string(obj) click to toggle source
# File lib/rmagick_internal.rb, line 243
def to_string(obj)
  return obj if obj.is_a?(String)
  return obj.to_s if obj.is_a?(Symbol)
  return obj.to_str if obj.respond_to?(:to_str)

  Kernel.raise TypeError, "no implicit conversion of #{obj.class} into String"
end