3.2.1 Boolean Masks

Overview

The next subtopic — masking and compositing — runs on a single idea: a boolean mask is a 2D array of True/False values, one per pixel, that decides where an operation applies. Where the mask is True, the operation fires; where it is False, the original pixels are left untouched. Every alpha channel, every layer mask in Photoshop, every “select all blue pixels” tool comes down to the same construction [1]. This lesson focuses on the boolean operation itself: build a mask from a geometric condition, apply it with NumPy fancy indexing, and read it as a single composable operator that the rest of the subtopic builds on.

Learning objectives

1. Build a 2D boolean mask from a geometric condition (a circle, a rectangle, a vertical band).
2. Apply a mask with fancy indexing — image[mask] = value — and predict which pixels get touched.
3. Combine multiple masks with &, |, and ~ to express AND, OR, and NOT.
4. Use a colour-channel threshold (image[:, :, 2] > 180) as a content-aware mask source.

Quick start — a circular vignette

import numpy as np
from PIL import Image

image = np.array(Image.open('bbtor.jpg'))   # any RGB photo will do
h, w = image.shape[:2]

# Grid of pixel coordinates
Y, X = np.ogrid[:h, :w]

# Distance² from the image centre — cheap because we never sqrt
cx, cy = w / 2, h / 2
distance_sq = (X - cx) ** 2 + (Y - cy) ** 2

# Mask: True where the pixel is *outside* the circle
outside = distance_sq > (w * h) / 6

# Blacken every "outside" pixel
image[outside] = 0

Image.fromarray(image).save('mask.png')

Core concepts

Concept 1 — A mask is a (H, W) boolean array

Every per-pixel operation in this subtopic needs an answer to the same question: should I touch this pixel? The cleanest place to keep that answer is a 2D array with one bool per pixel, called a mask.

mask = some_condition_over_pixel_coordinates   # shape (H, W), dtype bool

You build the mask from a vectorised expression — a comparison, a range check, a colour-channel threshold. Anything that produces a (H, W) boolean output is valid. NumPy’s ogrid is the standard way to materialise the coordinate grid:

Y, X = np.ogrid[:h, :w]                # X has shape (1, w), Y has shape (h, 1)
mask = (X - cx) ** 2 + (Y - cy) ** 2 < r_sq    # circle interior, shape (h, w)

The fact that the coordinate inputs to the condition are arrays — not Python loops — is what makes the mask cheap. The whole evaluation runs in vectorised C.

Concept 2 — Applying a mask with fancy indexing

Three patterns recur. All three use the mask as a selector on the left of =.

Solid colour where True.

image[mask] = [255, 0, 0]    # everywhere the mask is True → red

Copy from another image where True.

image[mask] = other[mask]    # everywhere the mask is True → take from other

Per-channel edit.

image[mask, 0] = 0            # zero out the red channel only, where the mask is True

Notice that the right-hand side never has to match the shape of the masked region — NumPy broadcasts. A 3-element list becomes the colour for every selected pixel; a same-shape other[mask] substitutes pixel-for-pixel.

Concept 3 — Boolean algebra on masks

Two masks combine with the same & | ~ operators you would use on individual booleans. Because the operands are NumPy arrays, the bitwise operators are the correct ones — and/or would short-circuit on the whole array as a single truth value and throw.

inner_circle = (X - cx)**2 + (Y - cy)**2 < r1_sq
outer_circle = (X - cx)**2 + (Y - cy)**2 < r2_sq

ring   = outer_circle & ~inner_circle      # AND NOT — inside outer but not inner
either = outer_circle | top_half_strip     # OR
not_in_circle = ~inner_circle              # negation

The boolean algebra is exactly what lets you build complex masks compositionally — a vignette, a ring, a chequered window, a colour-thresholded patch — without ever leaving NumPy.

Exercises

Three exercises in Execute → Modify → Create order: run the vignette, swap the mask formula, then build a custom shape mask of your own.

inside = distance_sq < (w * h) / 6
image[inside] = 0

band_half = w // 6
keep_band = (X >= cx - band_half) & (X < cx + band_half)
image[~keep_band] = 0

r_sq = (min(w, h) / 4) ** 2
left  = (X - w/3) ** 2 + (Y - h/2) ** 2 < r_sq
right = (X - 2*w/3) ** 2 + (Y - h/2) ** 2 < r_sq
keep = left | right
image[~keep] = 0

import numpy as np
from PIL import Image

image = np.array(Image.open('bbtor.jpg'))
h, w = image.shape[:2]

# Normalise coordinates so the heart can be tuned in (−1, 1)
Y, X = np.ogrid[:h, :w]
nx = (X - w / 2) / (w / 2)
ny = (Y - h / 2) / (h / 2)
ny = -ny     # flip y so the heart points "up" on screen

# TODO 1: build the heart mask. Two starter routes — pick one.
# Algebraic curve:
#   (x² + y² − 1)³ − x² · y³ < 0  is the inside of a heart.
# Or: two circles for the lobes + a downward triangle for the point.

# TODO 2: blacken everything *outside* the heart.

Image.fromarray(image).save('heart_mask.png')

heart_inside = (nx**2 + ny**2 - 1) ** 3 - nx**2 * ny**3 < 0

lobe_l  = (nx + 0.35)**2 + (ny - 0.30)**2 < 0.2
lobe_r  = (nx - 0.35)**2 + (ny - 0.30)**2 < 0.2
v_top   = 0.50
v_left  = -0.85
v_right =  0.85
v_bot   = -0.95
# inside a triangle: three half-plane tests AND'd
triangle = (ny > v_bot) & (ny < v_top - 0.4 * np.abs(nx)) & (np.abs(nx) < 0.85)
heart_inside = lobe_l | lobe_r | triangle

import numpy as np
from PIL import Image

image = np.array(Image.open('bbtor.jpg'))
h, w = image.shape[:2]

Y, X = np.ogrid[:h, :w]
nx = (X - w / 2) / (w / 2)
ny = -((Y - h / 2) / (h / 2))   # flip y

# Algebraic heart curve
heart_inside = (nx**2 + ny**2 - 1) ** 3 - nx**2 * ny**3 < 0

# Blacken outside
image[~heart_inside] = 0

Image.fromarray(image).save('heart_mask.png')

Downloads

Summary

Common pitfalls to avoid

• Using Python’s and/or instead of &/| — the former raise on whole arrays; only the bitwise operators broadcast.
• Building a (H, W, 3) mask when a (H, W) mask would do — indexing semantics differ in surprising ways.
• Forgetting parentheses around chained comparisons: (X > 100) & (X < 200) is correct; X > 100 & X < 200 is parsed as X > (100 & X) < 200 and crashes.
• Computing sqrt(d²) when you only need to compare against a radius — squaring the radius and skipping sqrt is faster and numerically cleaner.
• Assigning a tuple image[mask] = (255, 0, 0) — works, but a list [255, 0, 0] is the more conventional NumPy style.

References