`ImageDraw` module¶

TheImageDraw module provides simple 2D graphics forImage objects. You can use this module to create newimages, annotate or retouch existing images, and to generate graphics on thefly for web use.

For a more advanced drawing library for PIL, see theaggdraw module.

Example: Draw a gray cross over an image¶

importsysfromPILimportImage,ImageDrawwithImage.open("hopper.jpg")asim:draw=ImageDraw.Draw(im)draw.line((0,0)+im.size,fill=128)draw.line((0,im.size[1],im.size[0],0),fill=128)# write to stdoutim.save(sys.stdout,"PNG")

Concepts¶

Coordinates¶

The graphics interface uses the same coordinate system as PIL itself, with (0,0) in the upper left corner. Any pixels drawn outside of the image bounds willbe discarded.

Colors¶

To specify colors, you can use numbers or tuples just as you would use withPIL.Image.new(). SeeColors for more information.

For palette images (mode “P”), use integers as color indexes. In 1.1.4 andlater, you can also use RGB 3-tuples or color names (see below). The drawinglayer will automatically assign color indexes, as long as you don’t draw withmore than 256 colors.

Color names¶

SeeColor names for the color names supported by Pillow.

Alpha channel¶

By default, when drawing onto an existing image, the image’s pixel values are simplyreplaced by the new color:

im=Image.new("RGBA",(1,1),(255,0,0))d=ImageDraw.Draw(im)d.rectangle((0,0,1,1),(0,255,0,127))assertim.getpixel((0,0))==(0,255,0,127)# Alpha channel values have no effect when drawing with RGB modeim=Image.new("RGB",(1,1),(255,0,0))d=ImageDraw.Draw(im)d.rectangle((0,0,1,1),(0,255,0,127))assertim.getpixel((0,0))==(0,255,0)

If you would like to combine translucent color with an RGB image, then initialize theImageDraw instance with the RGBA mode:

fromPILimportImage,ImageDrawim=Image.new("RGB",(1,1),(255,0,0))d=ImageDraw.Draw(im,"RGBA")d.rectangle((0,0,1,1),(0,255,0,127))assertim.getpixel((0,0))==(128,127,0)

If you would like to combine translucent color with an RGBA image underneath, you willneed to combine multiple images:

fromPILimportImage,ImageDrawim=Image.new("RGBA",(1,1),(255,0,0,255))im2=Image.new("RGBA",(1,1))d=ImageDraw.Draw(im2)d.rectangle((0,0,1,1),(0,255,0,127))im.paste(im2.convert("RGB"),mask=im2)assertim.getpixel((0,0))==(128,127,0,255)

Fonts¶

PIL can use bitmap fonts or OpenType/TrueType fonts.

Bitmap fonts are stored in PIL’s own format, where each font typically consistsof two files, one named .pil and the other usually named .pbm. The formercontains font metrics, the latter raster data.

To load a bitmap font, use the load functions in theImageFontmodule.

To load a OpenType/TrueType font, use the truetype function in theImageFont module. Note that this function depends on third-partylibraries, and may not available in all PIL builds.

Example: Draw partial opacity text¶

fromPILimportImage,ImageDraw,ImageFont# get an imagewithImage.open("Pillow/Tests/images/hopper.png").convert("RGBA")asbase:# make a blank image for the text, initialized to transparent text colortxt=Image.new("RGBA",base.size,(255,255,255,0))# get a fontfnt=ImageFont.truetype("Pillow/Tests/fonts/FreeMono.ttf",40)# get a drawing contextd=ImageDraw.Draw(txt)# draw text, half opacityd.text((10,10),"Hello",font=fnt,fill=(255,255,255,128))# draw text, full opacityd.text((10,60),"World",font=fnt,fill=(255,255,255,255))out=Image.alpha_composite(base,txt)out.show()

Example: Draw multiline text¶

fromPILimportImage,ImageDraw,ImageFont# create an imageout=Image.new("RGB",(150,100),(255,255,255))# get a fontfnt=ImageFont.truetype("Pillow/Tests/fonts/FreeMono.ttf",40)# get a drawing contextd=ImageDraw.Draw(out)# draw multiline textd.multiline_text((10,10),"Hello\nWorld",font=fnt,fill=(0,0,0))out.show()

Functions¶

PIL.ImageDraw.Draw(im,mode=None)[source]¶

Creates an object that can be used to draw in the given image.

Note that the image will be modified in place.

Parameters:

im – The image to draw in.
mode – Optional mode to use for color values. For RGBimages, this argument can be RGB or RGBA (to blend thedrawing into the image). For all other modes, this argumentmust be the same as the image mode. If omitted, the modedefaults to the mode of the image.

Attributes¶

ImageDraw.fill:bool=False¶: Selects whetherImageDraw.ink should be used as a fill or outline color.

ImageDraw.font¶

The current default font.

Can be set per instance:

fromPILimportImageDraw,ImageFontdraw=ImageDraw.Draw(image)draw.font=ImageFont.truetype("Tests/fonts/FreeMono.ttf")

Or globally for all future ImageDraw instances:

fromPILimportImageDraw,ImageFontImageDraw.ImageDraw.font=ImageFont.truetype("Tests/fonts/FreeMono.ttf")

ImageDraw.fontmode¶

The current font drawing mode.

Set to"1" to disable antialiasing or"L" to enable it.

ImageDraw.ink:int¶: The internal representation of the current default color.

Methods¶

ImageDraw.getfont()[source]¶

Get the current default font,ImageDraw.font.

If the current default font isNone,it is initialized withImageFont.load_default().

Returns:: An image font.

ImageDraw.arc(xy,start,end,fill=None,width=0)[source]¶

Draws an arc (a portion of a circle outline) between the start and endangles, inside the given bounding box.

Parameters:

xy – Two points to define the bounding box. Sequence of[(x0,y0),(x1,y1)] or[x0,y0,x1,y1], wherex1>=x0 andy1>=y0.
start – Starting angle, in degrees. Angles are measured from 3o’clock, increasing clockwise.
end – Ending angle, in degrees.
fill – Color to use for the arc.
width –
The line width, in pixels.
Added in version 5.3.0.

ImageDraw.bitmap(xy,bitmap,fill=None)[source]¶

Draws a bitmap (mask) at the given position, using the current fill colorfor the non-zero portions. The bitmap should be a valid transparency mask(mode “1”) or matte (mode “L” or “RGBA”).

This is equivalent to doingimage.paste(xy,color,bitmap).

To paste pixel data into an image, use thepaste() method on the image itself.

ImageDraw.chord(xy,start,end,fill=None,outline=None,width=1)[source]¶

Same asarc(), but connects the end pointswith a straight line.

Parameters:

xy – Two points to define the bounding box. Sequence of[(x0,y0),(x1,y1)] or[x0,y0,x1,y1], wherex1>=x0 andy1>=y0.
outline – Color to use for the outline.
fill – Color to use for the fill.
width –
The line width, in pixels.
Added in version 5.3.0.

ImageDraw.circle(xy,radius,fill=None,outline=None,width=1)[source]¶

Draws a circle with a given radius centering on a point.

Added in version 10.4.0.

Parameters:

xy – The point for the center of the circle, e.g.(x,y).
radius – Radius of the circle.
outline – Color to use for the outline.
fill – Color to use for the fill.
width – The line width, in pixels.

ImageDraw.ellipse(xy,fill=None,outline=None,width=1)[source]¶

Draws an ellipse inside the given bounding box.

Parameters:

xy – Two points to define the bounding box. Sequence of either[(x0,y0),(x1,y1)] or[x0,y0,x1,y1], wherex1>=x0andy1>=y0.
outline – Color to use for the outline.
fill – Color to use for the fill.
width –
The line width, in pixels.
Added in version 5.3.0.

ImageDraw.line(xy,fill=None,width=0,joint=None)[source]¶

Draws a line between the coordinates in thexy list.The coordinate pixels are included in the drawn line.

Parameters:

xy – Sequence of either 2-tuples like[(x,y),(x,y),...] ornumeric values like[x,y,x,y,...].
fill – Color to use for the line.
width –
The line width, in pixels.
Added in version 1.1.5.
Note
This option was broken until version 1.1.6.
joint –
Joint type between a sequence of lines. It can be"curve", for rounded edges, orNone.
Added in version 5.3.0.

ImageDraw.pieslice(xy,start,end,fill=None,outline=None,width=1)[source]¶

Same as arc, but also draws straight lines between the end points and thecenter of the bounding box.

Parameters:

xy – Two points to define the bounding box. Sequence of[(x0,y0),(x1,y1)] or[x0,y0,x1,y1], wherex1>=x0 andy1>=y0.
start – Starting angle, in degrees. Angles are measured from 3o’clock, increasing clockwise.
end – Ending angle, in degrees.
fill – Color to use for the fill.
outline – Color to use for the outline.
width –
The line width, in pixels.
Added in version 5.3.0.

ImageDraw.point(xy,fill=None)[source]¶

Draws points (individual pixels) at the given coordinates.

Parameters:

xy – Sequence of either 2-tuples like[(x,y),(x,y),...] ornumeric values like[x,y,x,y,...].
fill – Color to use for the point.

ImageDraw.polygon(xy,fill=None,outline=None,width=1)[source]¶

Draws a polygon.

The polygon outline consists of straight lines between the givencoordinates, plus a straight line between the last and the firstcoordinate. The coordinate pixels are included in the drawn polygon.

Parameters:

xy – Sequence of either 2-tuples like[(x,y),(x,y),...] ornumeric values like[x,y,x,y,...].
fill – Color to use for the fill.
outline – Color to use for the outline.
width – The line width, in pixels.

ImageDraw.regular_polygon(bounding_circle,n_sides,rotation=0,fill=None,outline=None,width=1)[source]¶

Draws a regular polygon inscribed inbounding_circle,withn_sides, and rotation ofrotation degrees.

Parameters:

bounding_circle – The bounding circle is a tuple definedby a point and radius.(e.g.bounding_circle=(x,y,r) or((x,y),r)).The polygon is inscribed in this circle.
n_sides – Number of sides(e.g.n_sides=3 for a triangle,6 for a hexagon).
rotation – Apply an arbitrary rotation to the polygon(e.g.rotation=90, applies a 90 degree rotation).
fill – Color to use for the fill.
outline – Color to use for the outline.
width – The line width, in pixels.

ImageDraw.rectangle(xy,fill=None,outline=None,width=1)[source]¶

Draws a rectangle.

Parameters:

xy – Two points to define the bounding box. Sequence of either[(x0,y0),(x1,y1)] or[x0,y0,x1,y1], wherex1>=x0 andy1>=y0. The bounding box is inclusive of both endpoints.
fill – Color to use for the fill.
outline – Color to use for the outline.
width –
The line width, in pixels.
Added in version 5.3.0.

ImageDraw.rounded_rectangle(xy,radius=0,fill=None,outline=None,width=1,corners=None)[source]¶

Draws a rounded rectangle.

Parameters:

xy – Two points to define the bounding box. Sequence of either[(x0,y0),(x1,y1)] or[x0,y0,x1,y1], wherex1>=x0 andy1>=y0. The bounding box is inclusive of both endpoints.
radius – Radius of the corners.
fill – Color to use for the fill.
outline – Color to use for the outline.
width – The line width, in pixels.
corners – A tuple of whether to round each corner,(top_left,top_right,bottom_right,bottom_left).Keyword-only argument.

Added in version 8.2.0.

ImageDraw.shape(shape,fill=None,outline=None)[source]¶: Warning
This method is experimental.
Draw a shape.

ImageDraw.text(xy,text,fill=None,font=None,anchor=None,spacing=4,align='left',direction=None,features=None,language=None,stroke_width=0,stroke_fill=None,embedded_color=False,font_size=None)[source]¶

Draws the string at the given position.

Parameters:

xy – The anchor coordinates of the text.
text – String to be drawn. If it contains any newline characters,the text is passed on tomultiline_text().
fill – Color to use for the text.
font – AnImageFont instance.
anchor –
The text anchor alignment. Determines the relative location ofthe anchor to the text. The default alignment is top left,specificallyla for horizontal text andlt forvertical text. SeeText anchors for details.This parameter is ignored for non-TrueType fonts.
Note
This parameter was present in earlier versionsof Pillow, but implemented only in version 8.0.0.
spacing – If the text is passed on tomultiline_text(),the number of pixels between lines.
align –
If the text is passed on tomultiline_text(),"left","center","right" or"justify". Determinesthe relative alignment of lines. Use theanchor parameter tospecify the alignment toxy.
Added in version 11.2.1:"justify"
direction –
Direction of the text. It can be"rtl" (right toleft),"ltr" (left to right) or"ttb" (top to bottom).Requires libraqm.
Added in version 4.2.0.
features –
A list of OpenType font features to be used during textlayout. This is usually used to turn on optionalfont features that are not enabled by default,for example"dlig" or"ss01", but can be alsoused to turn off default font features, forexample"-liga" to disable ligatures or"-kern"to disable kerning. To get all supportedfeatures, seeOpenType docs.Requires libraqm.
Added in version 4.2.0.
language –
Language of the text. Different languages may usedifferent glyph shapes or ligatures. This parameter tellsthe font which language the text is in, and to apply thecorrect substitutions as appropriate, if available.It should be aBCP 47 language code.Requires libraqm.
Added in version 6.0.0.
stroke_width –
The width of the text stroke.
Added in version 6.2.0.
stroke_fill –
Color to use for the text stroke. If not given, will default tothefill parameter.
Added in version 6.2.0.
embedded_color –
Whether to use font embedded color glyphs (COLR, CBDT, SBIX).
Added in version 8.0.0.
font_size –
Iffont is not provided, then the size to use for the default
font.Keyword-only argument.
Added in version 10.1.0.

ImageDraw.multiline_text(xy,text,fill=None,font=None,anchor=None,spacing=4,align='left',direction=None,features=None,language=None,stroke_width=0,stroke_fill=None,embedded_color=False,font_size=None)[source]¶

Draws the string at the given position.

Parameters:

xy – The anchor coordinates of the text.
text – String to be drawn.
fill – Color to use for the text.
font – AnImageFont instance.
anchor –
The text anchor alignment. Determines the relative location ofthe anchor to the text. The default alignment is top left,specificallyla for horizontal text andlt forvertical text. SeeText anchors for details.This parameter is ignored for non-TrueType fonts.
Note
This parameter was present in earlier versionsof Pillow, but implemented only in version 8.0.0.
spacing – The number of pixels between lines.
align –
"left","center","right" or"justify". Determinesthe relative alignment of lines. Use theanchor parameter tospecify the alignment toxy.
Added in version 11.2.1:"justify"
direction –
Direction of the text. It can be"rtl" (right toleft),"ltr" (left to right) or"ttb" (top to bottom).Requires libraqm.
Added in version 4.2.0.
features –
A list of OpenType font features to be used during textlayout. This is usually used to turn on optionalfont features that are not enabled by default,for example"dlig" or"ss01", but can be alsoused to turn off default font features, forexample"-liga" to disable ligatures or"-kern"to disable kerning. To get all supportedfeatures, seeOpenType docs.Requires libraqm.
Added in version 4.2.0.
language –
Language of the text. Different languages may usedifferent glyph shapes or ligatures. This parameter tellsthe font which language the text is in, and to apply thecorrect substitutions as appropriate, if available.It should be aBCP 47 language code.Requires libraqm.
Added in version 6.0.0.
stroke_width –
The width of the text stroke.
Added in version 6.2.0.
stroke_fill –
Color to use for the text stroke. If not given, will default to
thefill parameter.
Added in version 6.2.0.
embedded_color –
Whether to use font embedded color glyphs (COLR, CBDT, SBIX).
Added in version 8.0.0.
font_size –
Iffont is not provided, then the size to use for the default
font.Keyword-only argument.
Added in version 10.1.0.

ImageDraw.textlength(text,font=None,direction=None,features=None,language=None,embedded_color=False,font_size=None)[source]¶

Returns length (in pixels with 1/64 precision) of given text when renderedin font with provided direction, features, and language.

This is the amount by which following text should be offset.Text bounding box may extend past the length in some fonts,e.g. when using italics or accents.

The result is returned as a float; it is a whole number if using basic layout.

Note that the sum of two lengths may not equal the length of a concatenatedstring due to kerning. If you need to adjust for kerning, include the followingcharacter and subtract its length.

For example, instead of

hello=draw.textlength("Hello",font)world=draw.textlength("World",font)hello_world=hello+world# not adjusted for kerningasserthello_world==draw.textlength("HelloWorld",font)# may fail

use

hello=draw.textlength("HelloW",font)-draw.textlength("W",font)# adjusted for kerningworld=draw.textlength("World",font)hello_world=hello+world# adjusted for kerningasserthello_world==draw.textlength("HelloWorld",font)# True

or disable kerning with (requires libraqm)

hello=draw.textlength("Hello",font,features=["-kern"])world=draw.textlength("World",font,features=["-kern"])hello_world=hello+world# kerning is disabled, no need to adjustasserthello_world==draw.textlength("HelloWorld",font,features=["-kern"])# True

Movatterモバイル変換

ImageDraw module¶

Example: Draw a gray cross over an image¶

Concepts¶

Coordinates¶

Colors¶

Color names¶

Alpha channel¶

Fonts¶

Example: Draw partial opacity text¶

Example: Draw multiline text¶

Functions¶

Attributes¶

Methods¶

`ImageDraw` module¶