Skip to content
Tutorials Center
My learning

Topics

Lesson 35 of 49 ยท Working with Real Data

Working with Real Images in NumPy

Load and save real image files with Pillow, convert them to NumPy arrays, work with channels, crop, flip, mask and resize them, and avoid uint8 and mode traps.

A digital picture is a grid of numbers, so an image is the most natural real-world NumPy array. The previous images lesson generated pictures from formulas. This lesson connects NumPy to real image files: you will decode a PNG or JPEG into an array, edit it with array operations, and encode it back into a file.

NumPy itself cannot read image formats. The standard helper is Pillow (imported as PIL), which understands PNG, JPEG, GIF, WebP and many other formats. Install it with python -m pip install pillow. Other libraries such as imageio, OpenCV and scikit-image do similar work and also return NumPy arrays.

Note: The examples in the browser have no files, so each one creates an image in memory, saves it to an io.BytesIO buffer (a file in memory) and reads it back. On your computer you replace the buffer with a file name, for example Image.open("photo.jpg").

From file to array and back

Two functions do the conversion. Image.open(...) decodes a file into a Pillow image object. np.asarray(image) gives a NumPy array view of its pixels, and Image.fromarray(array) goes the other way:

Python Image to array to image

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Study the details because they cause many bugs:

  • Pillow's size is (width, height), but an array's shape is (height, width, channels): rows come first. Do not mix them up.
  • An RGB image has shape (h, w, 3) and dtype uint8, with values 0 to 255.
  • PNG is lossless, so the round trip returns exactly the same pixels. JPEG is lossy, so it does not (see below).
  • np.asarray may return a read-only view. If you want to edit the pixels, call np.array(img) (a copy) or pixels.copy().

Modes and channels

The mode of an image says how its channels are arranged:

Mode Meaning Array shape
L Grayscale, 8 bits (h, w)
RGB Red, green, blue (h, w, 3)
RGBA RGB plus an alpha (transparency) channel (h, w, 4)
1 Black and white, 1 bit (h, w) of bool
P Palette: pixel values are indexes into a colour table (h, w) of indexes

Always convert to the mode you expect, because files arrive in any mode. A PNG icon with transparency is RGBA; a scanned page may be L; GIFs are usually P. img.convert("RGB") makes all of them uniform before you start.

Python Channels, grayscale and transparency

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

A single channel is a 2D array: arr[..., 0] is the red plane. Splitting channels is plain NumPy slicing, as in Indexing and Slicing.

Editing with array operations

Once an image is an array, every NumPy skill applies. Cropping is slicing, flipping is a reversed slice, brightness is arithmetic, and masks select regions:

Python Crop, flip, mask and tint

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Note the pattern in the tint: convert to float32, multiply, np.clip to 0 to 255, then convert back to uint8. Doing the multiplication directly on uint8 data would wrap around (see the traps below). The trailing factor [1.2, 1.0, 0.8] works through broadcasting: one number per colour channel.

Resizing and rotating

For resizing you want proper resampling, which NumPy does not provide. Use Pillow, then convert back to an array. Pillow's resize takes (width, height):

Python Resize and rotate with Pillow

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

np.rot90, flips and strided slicing work without Pillow, but they do not smooth anything. Taking every second pixel (arr[::2, ::2]) can create jagged artefacts, which is why Pillow's LANCZOS and BILINEAR filters are better for photos.

JPEG is lossy, PNG is lossless

JPEG saves space by discarding detail the eye barely notices. Each save at a lower quality changes the pixel values slightly. Measure the damage with NumPy:

Python How much does JPEG change the pixels?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

PNG always has an error of exactly 0, and for these flat synthetic pictures the PNG is even smaller (JPEG wins on real photographs, which PNG compresses poorly). JPEG's error is small on smooth areas and larger on noisy detail, and a lower quality gives a smaller file with a larger error. The rule: use PNG for diagrams, screenshots and data you will process again; use JPEG for photographs you only display; never re-save the same JPEG repeatedly in a processing pipeline.

Traps to remember

  • uint8 wraparound: img + 100 can turn bright pixels dark. Widen to int16 or float32, compute, clip, convert back (see the previous lesson). In the error calculation above, .astype(int) is essential: subtracting two uint8 arrays wraps around, too.
  • Height and width order: Pillow size is (w, h); array shape is (h, w, ...); resize takes (w, h).
  • Modes: convert with .convert("RGB") first. An RGBA file has four channels, and an L image has no channel axis at all.
  • Read-only arrays: np.asarray(img) might not be writable; use np.array(img) for a copy you can edit.
  • Memory: a 12-megapixel photo is 4000 * 3000 * 3 bytes = 36 MB as uint8 and 144 MB as float32. Process large files in tiles, or downscale first.
  • EXIF rotation: photos from phones may carry an orientation tag. ImageOps.exif_transpose(img) applies it so that the array is upright.

Saving the result

Convert the array back with Image.fromarray(result) and call .save("out.png"). For float arrays, scale to 0 to 255 and cast to uint8 first; fromarray would otherwise create a floating-point image that most formats cannot store. If you use Matplotlib for display only, plt.imsave("out.png", arr) also works for arrays.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. A Pillow image has size (200, 100). What is the shape of np.asarray(img) for an RGB image?

    Pillow's size is (width, height), while an array's shape starts with rows, which is the height: (height, width, channels).
  2. 2. Why is the lossless/lossy difference between PNG and JPEG important when processing?

    JPEG discards detail to save space, so a round trip does not return the same pixels. PNG is lossless.
  3. 3. What is the safe way to brighten a uint8 image by 40 levels?

    Adding in a wider type avoids wraparound; clip keeps values in range; converting back gives a valid uint8 image.
  4. 4. Which call gives you a copy of the pixels that you can edit freely?

    np.array copies by default. np.asarray may return a read-only view of the image data.
  5. 5. What does img.convert('RGB') protect you from?

    Image files can arrive in different modes, which change the number of channels. Converting first gives a predictable (h, w, 3) array.

Summary

  • NumPy does not read image files; Pillow does: Image.open then np.asarray or np.array, and Image.fromarray(...).save(...) to write.
  • RGB arrays have shape (height, width, 3) and dtype uint8; Pillow's size is (width, height).
  • Convert modes first (.convert("RGB")); L is (h, w) and RGBA has four channels.
  • Crop with slices, flip with [::-1], mask with boolean arrays, tint through broadcasting, and clip after float math.
  • Resize and rotate with Pillow for proper resampling; np.rot90 and strided slicing are quick but crude.
  • PNG is lossless and JPEG is lossy; widen before arithmetic to avoid uint8 wraparound.

Next: Signals and FFT applies the same array thinking to one-dimensional data.