ImageMagick: Command-line Options

ImageMagick: Command-line Options DRAW

-draw string

Annotate an image with one or more graphic primitives.

Use this option to annotate or decorate an image with one or more graphic primitives. The primitives include shapes, text, transformations, and pixel operations.

The shape primitives:

   point           x,y
   line            x0,y0 x1,y1
   rectangle       x0,y0 x1,y1
   roundRectangle  x0,y0 x1,y1 wc,hc
   arc             x0,y0 x1,y1 a0,a1
   ellipse         x0,y0 rx,ry a0,a1
   circle          x0,y0 x1,y1
   polyline        x0,y0  ...  xn,yn
   polygon         x0,y0  ...  xn,yn
   bezier          x0,y0  ...  xn,yn
   path            path specification
   image           operator x0,y0 w,h filename

The text primitive:

   text            x0,y0 string

The text gravity primitive:

   gravity         NorthWest, North, NorthEast, West, Center,
                   East, SouthWest, South, or SouthEast

The text gravity primitive only affects the placement of text and does not interact with the other primitives. It is equivalent to using the -gravity command-line option, except that it is limited in scope to the -draw option in which it appears.

The transformation primitives:

   rotate     degrees
   translate  dx,dy
   scale      sx,sy
   skewX      degrees
   skewY      degrees

The pixel operation primitives:

   color  x0,y0 method
   matte  x0,y0 method

The shape primitives are drawn in the color specified by the preceding -fill setting. For unfilled shapes, use -fill none. You can optionally control the stroke (the "outline" of a shape) with the -stroke and -strokewidth settings.

A point primitive is specified by a single point in the pixel plane, that is, by an ordered pair of integer coordinates, x,y. (As it involves only a single pixel, a point primitive is not affected by -stroke or -strokewidth.)

A line primitive requires a start point and end point.

A rectangle primitive is specified by the pair of points at the upper left and lower right corners.

A roundRectangle primitive takes the same corner points as a rectangle followed by the width and height of the rounded corners to be removed.

The circle primitive makes a disk (filled) or circle (unfilled). Give the center and any point on the perimeter (boundary).

The arc primitive is used to inscribe an elliptical segment in to a given rectangle. An arc requires the two corners used forrectangle (see above) followed by the start and end angles of the arc of the segment segment (e.g. 130,30 200,100 45,90). The start and end points produced are then joined with a line segment and the resulting segment of an ellipse is filled.

Use ellipse to draw a partial (or whole) ellipse. Give the center point, the horizontal and vertical "radii" (the semi-axes of the ellipse) and start and end angles in degrees (e.g. 100,100 100,150 0,360).

The polyline and polygon primitives require three or more points to define their perimeters. A polyline is simply apolygon in which the final point is not stroked to the start point. When unfilled, this is a polygonal line. If the -stroke setting is none (the default), then a polyline is identical to a polygon.

A coordinate is a pair of integers separated by a space or optional comma.

As an example, to define a circle centered at 100,100 that extends to 150,150 use:

-draw 'circle 100,100 150,150'

The Bezier primitive creates a spline curve and requires three or points to define its shape. The first and last points are theknots and these points are attained by the curve, while any intermediate coordinates are control points. If two control points are specified, the line between each end knot and its sequentially respective control point determines the tangent direction of the curve at that end. If one control point is specified, the lines from the end knots to the one control point determines the tangent directions of the curve at each end. If more than two control points are specified, then the additional control points act in combination to determine the intermediate shape of the curve. In order to draw complex curves, it is highly recommended either to use the path primitive or to draw multiple four-point bezier segments with the start and end knots of each successive segment repeated. For example:

-draw 'bezier 20,50 45,100 45,0 70,50'

-draw 'bezier 70,50 95,100 95,0 120,50'

A path represents an outline of an object, defined in terms of moveto (set a new current point), lineto (draw a straight line), curveto (draw a Bezier curve), arc (elliptical or circular arc) and closepath (close the current shape by drawing a line to the last moveto) elements. Compound paths (i.e., a path with subpaths, each consisting of a single moveto followed by one or more line or curve operations) are possible to allow effects such as donut holes in objects. (See Paths.)

Use image to composite an image with another image. Follow the image keyword with the composite operator, image location, image size, and filename:

-draw 'image SrcOver 100,100 225,225 image.jpg'

You can use 0,0 for the image size, which means to use the actual dimensions found in the image header. Otherwise, it is scaled to the given dimensions. See Alpha Compositing for a detailed discussion of alpha composition methods that are available.

The "special augmented compose operators" such as "dissolve" that require arguments cannot be used at present with the -draw image option.

Use text to annotate an image with text. Follow the text coordinates with a string. If the string has embedded spaces, enclose it in single or double quotes.

For example, the following annotates the image with Works like magick! for an image titled bird.miff.

-draw "text 100,100 'Works like magick!' "

See the -annotate option for another convenient way to annotate an image with text.

The rotate primitive rotates subsequent shape primitives and text primitives about the origin of the main image. If the -region option precedes the -draw option, the origin for transformations is the upper left corner of the region.

The translate primitive translates subsequent shape and text primitives.

The scale primitive scales them.

The skewX and skewY primitives skew them with respect to the origin of the main image or the region.

The transformations modify the current affine matrix, which is initialized from the initial affine matrix defined by the -affineoption. Transformations are cumulative within the -draw option. The initial affine matrix is not affected; that matrix is only changed by the appearance of another -affine option. If another -draw option appears, the current affine matrix is reinitialized from the initial affine matrix.

Use the color primitive to change the color of a pixel to the fill color (see -fill). Follow the pixel coordinate with a method:

   point
   replace
   floodfill
   filltoborder
   reset

Consider the target pixel as that specified by your coordinate. The point method recolors the target pixel. The replacemethod recolors any pixel that matches the color of the target pixel. Floodfill recolors any pixel that matches the color of the target pixel and is a neighbor, whereas filltoborder recolors any neighbor pixel that is not the border color. Finally,reset recolors all pixels.

Use matte to the change the pixel matte value to transparent. Follow the pixel coordinate with a method (see the colorprimitive for a description of methods). The point method changes the matte value of the target pixel. The replace method changes the matte value of any pixel that matches the color of the target pixel. Floodfill changes the matte value of any pixel that matches the color of the target pixel and is a neighbor, whereas filltoborder changes the matte value of any neighbor pixel that is not the border color (-bordercolor). Finally reset changes the matte value of all pixels.

You can set the primitive color, font, and font bounding box color with -fill, -font, and -box respectively. Options are processed in command line order so be sure to use these options before the -draw option.

Strings that begin with a number must be quoted (e.g. use '1.png' rather than 1.png).

Drawing primitives conform to the Magick Vector Graphics format.