The ImageDraw Module

The ImageDraw module provides simple 2D graphics support for Image objects. You can use this module to construct new graphics elements from scratch, annotate or patch existing image matrices, and generate operational charts or composite layouts on the fly for web runtime delivery systems.

Basic Implementation Example

The following sample routine reads a target image asset, instantiates an operational 2D drawing overlay, and paints a medium-grey cross across the pixel dimensions from boundary corners:

from PIL import Image, ImageDraw
import sys

try:
    # Open target background asset image
    im = Image.open("lena.pgm")
    
    # Initialize the drawing context surface wrapper
    draw = ImageDraw.Draw(im)
    
    # Render line parameters over coordinate vectors
    draw.line((0, 0) + im.size, fill=128)
    draw.line((0, im.size[1], im.size[0], 0), fill=128)
    
    # Explicitly clear rendering reference frame
    del draw 
    
    # Output binary data array to standard processing pipeline
    im.save(sys.stdout, "PNG")
except IOError:
    print("Failed to initialize target graphics coordinate paths.")

Core Operational Concepts

Coordinate Spaces

The pixel mapping vector system uses standard matrix offsets natively used by the root PIL library. The absolute origin point (0, 0) marks the top-left terminal corner pixel of the drawing canvas array, with variables incrementing rightward and downward.

Color Assignment Handling

To declare graphic boundary and fill profiles, colors are processed via data numbers or standard tuple variants depending on the image mode profile context:

Bi-level, Greyscale, and Integer Modes ("1", "L", "I"): Pass a standard discrete integer value mapping directly to target pixel depth.
TrueColor Space Modes ("RGB"): Pass a structured 3-element integer tuple representing standard 8-bit channel configurations: (red, green, blue).
Floating-Point Spaces ("F"): Pass standard real numeric configurations or floating-point parameters.
Palette Configurations ("P"): Pass raw numerical indexes pointing to target index colors. Color translation vectors automatically manage mapping up to the 256 spectrum limits.

String Formatting Color Specs

For standard "RGB" drawing passes, alternative string literals offer transparent parser handling:

Hexadecimal Identifiers: Declared explicitly as "#rgb" or "#rrggbb" blocks. For instance, "#ff0000" parses cleanly into absolute pure red.
Standard Functional RGB Enclosures: Given directly via rgb(R, G, B) syntax constraints containing explicit 8-bit values or proportional percentage blocks such as "rgb(255,0,0)" or "rgb(100%,0%,0%)".
HSL Color Mappings: Evaluated parameters utilizing the "hsl(hue, saturation%, lightness%)" formulation format. Hue tracks rotational degrees from 0 to 360, saturation details chroma density, and lightness maps values between absolute dark and white bounds.
HTML Common Names: Standard web names are parsed without structural case limitations. "Red" and "red" reference the identical absolute values.

Text Typographic Elements

Text primitives support both custom bitmapped distributions and system-wide TrueType/OpenType files. Bitmapped typographic allocations link a tracking metrics descriptor module (.pil) alongside the specific raster map file (.pbm). TrueType bindings use the external configuration resources loaded cleanly via the ImageFont module engine.

Factory Functions

Draw(image) ⇒ Draw instance

Spawns a custom 2D rendering overlay target context tracking structural parameters on the declared image structure block. Modifies memory arrays strictly in-place.

Drawing Methods

draw.arc(xy, start, end, options)

Paints an elliptical curve line boundary segment following structural angles mapped across bounding coordinates. Uses the outline value parameters to apply color passes.

draw.bitmap(xy, bitmap, options)

Fills custom matrix pixel overlays at tracking positions according to declared alpha values or standard "1" mask layouts. To drop complete canvas blocks inside target surfaces, rely on the core image paste() logic block.

draw.chord(xy, start, end, options)

Operates cleanly identical to the standard arc() function, but automatically closes the structural geometry paths by stretching a linear line connecting terminal node locations. Supports outline and inner fill options.

draw.ellipse(xy, options)

Constructs a closed elliptical boundary spanning across declared structural coordinates. Configured via custom outline path options and absolute inside fill color keys.

draw.line(xy, options)

Renders straight-line path vectors linking consecutive point definitions embedded within the xy coordinates array. Elements take the shape of numeric arrays or multi-tuple sequences.

The optional width parameters determine thickness. Polylines with high width limits might render with minor layout flaws at point intersections due to primitive vector limits.

draw.pieslice(xy, start, end, options)

Operates structurally like an arc() segment, but connects endpoints directly back to the center coordinate node of the bounding box boundary definition.

draw.point(xy, options)

Sets single tracking pixels directly onto specified canvas matrix coordinates inside the xy argument array sequence using explicit fill parameters.

draw.polygon(xy, options)

Renders a closed multi-point polygonal shape by generating linear line boundaries across consecutive points, automatically connecting the trailing node back to the initial coordinates sequence marker.

draw.rectangle(box, options)

Draws a 2D box shape. The coordinates sequence contains explicit parameters defining positional bounds. The bounding point limits evaluate structural edge paths up to the outer limit boundary margin profiles.

draw.text(position, string, options)

Prints target text strings down at position locations using the upper-left coordinate profile. Relies on the custom typographic configurations loaded cleanly via the font parameter instances.

draw.textsize(string, options) ⇒ (width, height)

Processes text metadata variables to calculate the bounding dimensional area required to map strings inside the drawing matrix canvas structure cleanly, returning an integer width-height pixel tuple.

Parameter Options Definitions

outline

Defines the bounding edge line color vector parameter. Accepts an integer, string, or channel tuple structural assignment format block.

fill

Declares the solid interior structural background fill color vector parameter. Maps configurations via identical depth parameters.

font

Binds custom typography objects. Links properties directly using loaded ImageFont active interface instances.

Backward Compatibility Blocks

The parameters and methods defined below serve strictly to support processing legacy application scripts. Avoid embedding these methods when developing modern processing files. Do not mix explicit parameter configurations with legacy style methods.

ImageDraw(image) ⇒ Deprecated Wrapper

Legacy class instance instantiation wrapper hook. Replace instances cleanly by initializing instances with the Draw(image) factory function instead.

draw.setink(ink) ⇒ Deprecated Method

Sets default color targets for upcoming primitive passes. Superseded natively by setting the color value inside functional fill arguments directly.

draw.setfill(mode) ⇒ Deprecated Method

Sets default filling toggles. Mode 0 outlines vector bounds; mode 1 forces background color layout fillings.

draw.setfont(font) ⇒ Deprecated Method

Sets the global fallback typeface instance used across subsequent text rendering invocations when explicit arguments are omitted.