imagedraw() for Image Coords: An Honest Dev's Review

pip install Pillow

from PIL import Image, ImageDraw

# Open an image file (or create a new one)
try:
    img = Image.open('path/to/your/image.jpg')
except FileNotFoundError:
    # If no image, create a blank one for demonstration
    img = Image.new('RGB', (600, 400), color = 'gray')

# Create a drawing context
draw = ImageDraw.Draw(img)

# Now you can use 'draw' to add shapes, text, etc.

# Don't forget to save your changes!
img.save('output.jpg')

It takes one primary argument: a list or tuple containing two coordinate pairs. This is the second major point of confusion.

draw.rectangle([(x0, y0), (x1, y1)], ...)

• (x0, y0): The coordinate for the top-left corner of the rectangle.
• (x1, y1): The coordinate for the bottom-right corner of the rectangle.

You can also specify fill for the interior color and outline for the border color.

from PIL import Image, ImageDraw

# Create a blank canvas for clarity
img = Image.new('RGB', (500, 300), color = '#f0f0f0')
draw = ImageDraw.Draw(img)

# Define the top-left and bottom-right corners
top_left = (50, 50)
bottom_right = (200, 150)

# Draw a red rectangle with a blue outline
draw.rectangle([top_left, bottom_right], fill="red", outline="blue", width=3)

# Let's draw another one, semi-transparent
# Note: To draw with transparency, the image mode needs to be 'RGBA'
img_rgba = img.convert("RGBA")
draw_rgba = ImageDraw.Draw(img_rgba)

# A semi-transparent green box (Red, Green, Blue, Alpha)
draw_rgba.rectangle([(250, 100), (450, 250)], fill=(0, 255, 0, 128))

img_rgba.save('rectangles_output.png')

Lines, Points, and Polygons

Other shapes follow similar logic. A line needs two points, a polygon needs at least three, and a point just needs one.

# ... continuing from the previous setup ...

# Draw a line from (300, 20) to (480, 50)
draw.line([(300, 20), (480, 50)], fill="black", width=5)

# Draw a single point at (25, 25)
# Note: 'point' is good for single pixels, not large dots.
draw.point([(25, 25)], fill="purple")

# Draw a polygon (a triangle in this case)
# It takes a sequence of (x,y) tuples
polygon_coords = [(100, 200), (150, 280), (50, 280)]
draw.polygon(polygon_coords, outline="green", fill="yellow")

img.save('various_shapes_output.jpg')

An Honest Dev's Take: Real-World Use Cases & Gotchas

Knowing the syntax is one thing; using it effectively is another. Here are some real-world tips and traps to watch out for.

Use Case: Visualizing Object Detection

This is a classic. Your machine learning model spits out a list of detections, often including a class label and a bounding box. Your job is to draw these boxes on the original image to see if the model is working correctly.

Let's say your model output for one image is:

detections = [{'box': [112, 60, 340, 250], 'label': 'cat'}]

The 'box' coordinates are already in the [x_min, y_min, x_max, y_max] format. This maps perfectly to Pillow's [(x0, y0), (x1, y1)] format. You can draw it directly!

# Assuming 'img' is your loaded image and 'draw' is its context

for detection in detections:
    box = detection['box']
    label = detection['label']
    
    # The box format [xmin, ymin, xmax, ymax] needs to be converted to [(x0,y0), (x1,y1)]
    box_coords = [(box[0], box[1]), (box[2], box[3])]
    
    draw.rectangle(box_coords, outline="lime", width=2)
    
    # You can also draw text
    text_position = (box[0] + 5, box[1] + 5) # Slightly inside the box
    draw.text(text_position, label, fill="lime")

img.show() # Display the image

Gotcha: Coordinate Formats (xywh vs. xyxy)

This is the big one. While Pillow's ImageDraw wants the top-left and bottom-right corners (often called xyxy format), many other libraries and frameworks (like COCO datasets or OpenCV) use a different format: [x, y, width, height] (often called xywh). Here, (x, y) is the top-left corner, and w and h are the box's dimensions.

If you pass an xywh box directly to draw.rectangle(), you'll get a tiny, incorrect rectangle drawn from (x, y) to (w, h). You must convert it first.

The conversion is simple:

• x0 = x
• y0 = y
• x1 = x + width
• y1 = y + height

Here's a helper function you'll use over and over:

def xywh_to_xyxy(box):
    x, y, w, h = box
    x0 = x
    y0 = y
    x1 = x + w
    y1 = y + h
    return [x0, y0, x1, y1]

# Example usage:
detection_xywh = {'box': [112, 60, 228, 190], 'label': 'cat'} # [x, y, width, height]

# Convert to the format Pillow needs
box_xyxy = xywh_to_xyxy(detection_xywh['box'])

# Now draw it (remembering to format as a list of tuples)
draw.rectangle([(box_xyxy[0], box_xyxy[1]), (box_xyxy[2], box_xyxy[3])], outline="magenta", width=3)

Gotcha: Integer Coordinates

Pillow's drawing functions expect integer coordinates. If you're getting coordinates from a model that outputs them as floats (e.g., normalized coordinates between 0 and 1), make sure you convert them to absolute pixel values and then cast them to integers before passing them to ImageDraw.

draw.rectangle([(int(x0), int(y0)), (int(x1), int(y1))])

Wrapping Up: Your Go-To for Image Drawing

That's really all there is to it for 95% of use cases. The complexity of ImageDraw isn't in its functions, but in understanding and respecting its coordinate system.

To recap the honest dev's checklist:

1. Origin Check: Is my (0,0) at the top-left? (Yes).
2. Axis Check: Does Y increase downwards? (Yes).
3. Format Check: Am I giving draw.rectangle() the top-left and bottom-right corners (xyxy), not xywh?
4. Type Check: Are my coordinates integers?

Keep these four points in mind, and you'll save yourself hours of head-scratching. Now go draw some boxes—correctly, on the first try.