Skip to content
Tutorials Center
My learning

Topics

Lesson 47 of 54 ยท Projects

Project: Color Object Detector

Build a color object detector: convert to HSV, threshold with inRange, clean the mask with morphology, then find contours and centroids. Live NumPy demo included.

Finding "the red ball" or "the green sticker" in an image is one of the most useful beginner projects in computer vision. It powers simple robots, color-based games, and quick prototypes where a full neural network would be overkill. The recipe has four steps: convert the image to HSV, keep only the pixels in a color range, clean the resulting mask, and measure each remaining blob.

The real pipeline uses cv2, which cannot run on this site, so it appears in read-only blocks. The live demos use a NumPy stand-in: we draw a synthetic scene with colored shapes and speckle noise, write our own BGR-to-HSV conversion with OpenCV's value ranges, clean the mask with erosion and dilation, and label the blobs ourselves. The math is the same as OpenCV's; it is only slower.

The detector in four steps

HSV Separate color from brightness.
Mask Keep pixels in a color range.
Clean Opening removes specks.
Measure Contours give boxes and centroids.
1 / 2

The real pipeline (read-only)

This is how you would do it with OpenCV on a photo or a webcam frame:

Python
import cv2
import numpy as np

image = cv2.imread("desk.jpg")                    # BGR, uint8
hsv = cv2.cvtColor(image, cv2.COLOR_BGR2HSV)      # H 0-179, S 0-255, V 0-255

# Red wraps around the hue circle, so it needs two ranges
low_red = cv2.inRange(hsv, (0, 120, 70), (10, 255, 255))
high_red = cv2.inRange(hsv, (170, 120, 70), (179, 255, 255))
mask = cv2.bitwise_or(low_red, high_red)

kernel = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (5, 5))
mask = cv2.morphologyEx(mask, cv2.MORPH_OPEN, kernel)    # remove specks
mask = cv2.morphologyEx(mask, cv2.MORPH_CLOSE, kernel)   # fill small holes

contours, _ = cv2.findContours(mask, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
for contour in contours:
    if cv2.contourArea(contour) < 200:
        continue
    x, y, w, h = cv2.boundingRect(contour)
    m = cv2.moments(contour)
    cx, cy = int(m["m10"] / m["m00"]), int(m["m01"] / m["m00"])
    cv2.rectangle(image, (x, y), (x + w, y + h), (0, 255, 0), 2)
    cv2.circle(image, (cx, cy), 4, (255, 255, 255), -1)

cv2.imwrite("detected.jpg", image)

Each call has its own lesson: Color Spaces for cvtColor and HSV, Arithmetic, Bitwise Ops and Masking for inRange, Morphological Operations for the cleanup, and Finding and Drawing Contours and Contour Features for the measuring.

Real vs stand-in: the code above is real OpenCV and cannot run here. In the demos below, cvtColor becomes our own bgr_to_hsv, inRange becomes a NumPy comparison, morphologyEx becomes shifted-array logic, and findContours plus moments become a flood-fill labeler. The numbers they produce follow the same definitions.

Step 1: HSV, and OpenCV's odd ranges

HSV describes a pixel by hue (which color), saturation (how vivid versus gray) and value (how bright). To pick "red" you need only a hue range plus a minimum saturation and value, which makes the rule resistant to shadows. In BGR, a dark red and a bright red have very different blue, green and red values and you would need a clumsy box around them.

OpenCV stores 8-bit HSV with H in 0 to 179 (the hue circle of 360 degrees halved, so it fits in a byte), and S and V in 0 to 255. That is why the common ranges look strange: pure red is H = 0, green is about 60, blue is about 120.

The function below follows the standard HSV formulas and reproduces those values.

Python BGR to HSV, with OpenCV's ranges

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.

Two things to read off the table. First, "red" and "dark red" share the same hue and saturation; only V changes, exactly why HSV survives shadows. Second, white and gray have saturation 0, so their hue is meaningless (it prints as 0). That is why every color rule needs a minimum saturation: without it, gray and white pixels would be reported as red.

Red is awkward because it sits at H = 0, right where the circle wraps. Real red pixels land at H = 0 to 10 or H = 170 to 179. Every red detector therefore combines two inRange masks with bitwise_or.

Step 2: build the mask and look at the noise

Our synthetic scene is 60 rows by 90 columns of dark background, with a red disc, a green rectangle, a blue disc and a handful of stray red speckles (like sensor noise or a red reflection). We build the mask for red and print it as text, first raw and then after a morphological opening: erosion (shrink every blob by one pixel on each side, which deletes anything smaller than the structuring element) followed by dilation (grow it back).

Python A synthetic scene and a noisy mask

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.

The raw mask (534 pixels) shows two shapes plus scattered single pixels. After opening (514 pixels), the speckles are gone and the two real objects remain, with only their sharpest corners trimmed. The general rule: opening removes small bright regions, closing fills small dark holes, and the right kernel size depends on how big your noise is compared with your smallest real object.

If you printed the green and blue masks too, you would see the same logic with different hue ranges: green around H 40 to 80, blue around H 100 to 130. Pick ranges by inspecting HSV values of your target, for example by printing the HSV of a pixel you click on.

Step 3: label blobs and measure them

After cleaning, each connected group of mask pixels is one candidate object. OpenCV's findContours traces the outline of each, and contourArea, boundingRect and moments summarise it. Our stand-in uses a flood-fill labeler that visits connected pixels (4-neighbours) and records their positions. From the pixel lists we get:

  • area = number of pixels,
  • centroid = mean column (x) and mean row (y), which is what m10/m00 and m01/m00 compute,
  • bounding box = min and max column and row.

Always filter by a minimum area to throw away anything that survived the cleanup but is still too small to be real.

Python The full detector: label, measure, annotate

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.

The report lists four objects (two red, one green, one blue) with their areas, centroids and boxes, and the text picture draws a rectangle of R, G or B letters around each with a + at the centroid. The 14 red speckles never appear: opening deleted them, and even if one had survived, the minimum-area filter would have dropped it.

Compare the centroid values with where the shapes were drawn: the big red disc was centred at column 22, row 20, and the detector reports its centre within a fraction of a pixel. That is the property to rely on in practice: centroids are far more precise than boxes.

Tuning and traps

  1. Pick ranges from data, not guesses. Print the HSV of a few target pixels, then widen by about plus or minus 10 in hue and set S and V minimums to reject gray and dark pixels.
  2. Lighting still matters. Very dim or washed-out regions have unstable hue. Raise the minimum saturation and value if you see false detections.
  3. Red needs two ranges (H near 0 and near 179).
  4. BGR, not RGB. If you build your own test images in cv2 code, remember the channel order, and note that cv2.cvtColor needs the matching code (COLOR_BGR2HSV versus COLOR_RGB2HSV). See Common Mistakes and Debugging.
  5. Kernel size should be smaller than your smallest real object and larger than your noise.
  6. For video, run this per frame and keep the centroid history to track movement. A ready next step is Motion and Object Tracking.

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. In OpenCV's 8-bit HSV format, what is the range of the hue channel?

    Hue is a 0-360 degree circle, halved to fit in a uint8, so OpenCV hue runs from 0 to 179. Saturation and value use the full 0 to 255.
  2. 2. Why does detecting red usually need two inRange calls combined with bitwise_or?

    Red hues land at the start and the end of the hue scale, so one continuous range cannot cover them both.
  3. 3. What does a morphological opening (erosion then dilation) do to a binary mask?

    Erosion deletes anything narrower than the structuring element, and dilation then grows the surviving blobs back. Closing (the reverse order) is the one that fills holes.
  4. 4. Why filter detected blobs by a minimum area?

    Some noise survives even a good cleanup. An area threshold is a cheap last filter.
  5. 5. A mid-gray pixel has saturation 0. Why does that matter for color rules?

    When saturation is 0 the hue is undefined and shows as 0, which looks like red. A minimum saturation keeps grays and whites out of color masks.

Summary

  • Convert to HSV so that color (hue) is separate from brightness; OpenCV uses H 0 to 179 and S, V 0 to 255.
  • Build a mask with inRange; red needs two ranges combined with bitwise_or. Require minimum saturation and value.
  • Clean the mask with opening (remove specks) and closing (fill holes) using a kernel suited to your noise.
  • Find blobs with findContours, then measure with contourArea, boundingRect and moments (centroid = m10/m00, m01/m00); filter by minimum area.
  • The live demo used NumPy stand-ins for each step; the cv2 code is read-only here.

Next project: Project: Lane Line Detection.