VMware ESXi and vSphere Cluster Management

Cropping Images with Pillow

Learn how to crop a rectangular region from an image with Python Pillow using pixel coordinates, crop boxes, and Image.crop().

What image cropping does

Image cropping extracts a selected rectangular portion of an existing image. The surrounding pixels are left out of the result, so cropping is useful for isolating a person, object, face, or other detail in a photograph.

Cropping is different from resizing. Cropping removes pixels around the outside of an image, while resizing changes the image dimensions by making the existing content larger or smaller.

Prerequisites

This lesson assumes basic Python variable assignment, Python tuples, importing packages, opening files with a path, and basic familiarity with raster images and pixels.

Pillow is a Python imaging library. Although the package is called Pillow, its Python modules are commonly imported through the PIL package namespace. The Image object is the Pillow object used to open, manipulate, preview, and save raster images.

Set up a Pillow image

Import the Image module from PIL:

from PIL import Image

Open a JPEG file with Image.open() and store the returned image object in a variable:

from PIL import Image

img = Image.open('handsome.jpg')

The variable img now refers to the opened source image. Keeping this object separate is useful because the original image remains available after you create a crop.

Understand Pillow pixel coordinates

Pixel coordinates are numeric horizontal and vertical positions within an image. Pillow uses an origin at (0, 0), located at the image's upper-left corner.

• The x value increases as you move to the right.
• The y value increases as you move downward.
• Coordinates are measured in pixels.

For example, a point at (100, 50) is 100 pixels from the left edge and 50 pixels down from the top edge. The y-axis does not increase upward as it does in some mathematical graphs.

Use the crop() method

Pillow's crop() method returns a new image containing the pixels inside a rectangular crop box:

cropped_img = img.crop(area)

The method is written as Image.crop(box) conceptually: call it on an image object and pass one four-value tuple that defines the rectangle. The tuple order is left, upper, right, lower.

The left and upper values identify the rectangle's top-left boundary. The right and lower values identify its bottom-right boundary. Pillow returns a new image object; it does not require overwriting the original image.

A crop box is this four-coordinate tuple. A tuple is an ordered Python collection written with parentheses. For a normal rectangle, right should be greater than left, and lower should be greater than upper.

Choose crop coordinates

Use an image editor or image-viewing tool that displays the cursor's pixel coordinates. Move the cursor to the desired top-left corner of the region and record that coordinate first. Then move it to the desired bottom-right corner and record that coordinate second.

1. Open the source image in a coordinate-aware image editor or viewer.
2. Identify the top-left boundary around the target detail.
3. Record its x and y values as left and upper.
4. Identify the bottom-right boundary around the target detail.
5. Record its x and y values as right and lower.
6. Make sure the rectangle encloses the complete subject or detail you want to extract.

For example, if the top-left coordinate is (555, 344) and the bottom-right coordinate is (598, 380), the crop box is (555, 344, 598, 380).

Create and apply a crop box

Store the four values in a named tuple, then pass that tuple to crop(). Assign the returned image to a separate variable:

from PIL import Image

img = Image.open('handsome.jpg')

area = (555, 344, 598, 380)
cropped_img = img.crop(area)

Here, img remains the complete opened image, while cropped_img contains only the selected rectangular region. Keeping two variables makes it possible to preview or process either version.

Preview the cropped image

Use the cropped image object's show() method for a quick local preview:

cropped_img.show()

Previewing verifies whether the coordinates captured the intended region. If the result misses part of the subject or includes too much surrounding area, adjust the crop box and preview it again.

Complete example

The following example opens a JPEG, defines a crop area, creates a separate cropped image, and displays the result:

from PIL import Image

img = Image.open('handsome.jpg')
area = (555, 344, 598, 380)
cropped_img = img.crop(area)
cropped_img.show()

Troubleshoot common problems

The crop is not the intended part of the image

Coordinates may have been measured incorrectly, or the selected top-left and bottom-right positions may not surround the desired detail. Recheck the cursor positions in the image editor, confirm the order is left, upper, right, lower, and preview the result before refining the values.

The crop is vertically shifted or appears incorrectly placed

This often happens when the y-axis is assumed to increase upward. Pillow starts at the upper-left, and y values increase as the position moves down. Recheck both vertical coordinates using that direction.

The crop call fails or produces an unexpected result

Pass one four-item tuple rather than separate, incorrectly ordered values:

area = (left, upper, right, lower)
cropped_img = img.crop(area)

Also ensure that right is to the right of left and lower is below upper.

The image file cannot be opened

Check that the filename and relative path are correct and that the script is running from the directory you expect. Use the correct relative or absolute path, confirm that the file is available and valid, and verify that Pillow is installed.

Key points

• Pillow is imported with from PIL import Image.
• Image.open() returns an image object that can be stored for later operations.
• The coordinate origin (0, 0) is at the upper-left.
• x increases to the right, and y increases downward.
• A crop box is a tuple in (left, upper, right, lower) order.
• crop() returns a new image object, leaving the source image available.
• show() provides a quick local preview of the cropped result.