Skip to content

OpenCV Aide-mémoire

Bibliothèque open source de vision par ordinateur et d'apprentissage automatique.

01

Premiers pas

Lire, afficher et sauvegarder des images

OpenCV lit les images en ordre BGR (pas RGB) — un piège classique en interopérant avec matplotlib ou PIL. cv2.waitKey(0) bloque jusqu'à une pression de touche ; appelez toujours destroyAllWindows() pour fermer les fenêtres. La qualité JPEG va de 0 à 100.

opencv
import cv2
import numpy as np

# read an image (BGR format by default)
img = cv2.imread("photo.jpg")
print(img.shape)  # (height, width, channels)

# read as grayscale
gray = cv2.imread("photo.jpg", cv2.IMREAD_GRAYSCALE)

# read with alpha channel
rgba = cv2.imread("logo.png", cv2.IMREAD_UNCHANGED)

# display
cv2.imshow("window", img)
cv2.waitKey(0)
cv2.destroyAllWindows()

# save
cv2.imwrite("output.jpg", img, [cv2.IMWRITE_JPEG_QUALITY, 90])

Installation et import

opencv-python n'embarque que les modules principaux ; opencv-contrib-python ajoute des modules supplémentaires (souvent entravés par des brevets) comme SIFT/SURF et ArUco. Utilisez la variante headless sur serveurs/Docker pour éviter de tirer des dépendances X11. Malgré le nom cv2, OpenCV 4.x s'importe toujours comme cv2.

opencv
# Install OpenCV (Python bindings)
pip install opencv-python          # main modules only
pip install opencv-contrib-python  # includes extra modules (SIFT, SURF, aruco...)
pip install opencv-python-headless # no GUI (servers / Docker)

# The universal alias is cv2
import cv2
print(cv2.__version__)             # e.g. 4.9.0

# NumPy is required — images are ndarray
import numpy as np

Image comme tableau NumPy

Les images OpenCV sont des tableaux NumPy, donc tout ce que vous savez de NumPy s'applique. La convention de coordonnées est img[y, x] (ligne, colonne) — l'inverse des coordonnées d'image (x, y), source fréquente de bugs. Les images couleur sont (H, W, 3) en BGR ; les niveaux de gris sont (H, W).

opencv
import cv2
import numpy as np

img = cv2.imread("photo.jpg")   # BGR uint8, shape (H, W, 3)
print(type(img))                # <class 'numpy.ndarray'>
print(img.shape, img.dtype)     # (480, 640, 3) uint8

# A grayscale image is 2-D: (H, W)
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
print(gray.shape)               # (480, 640)

# Coordinate convention: img[y, x]  (row, col)
px = img[100, 200]              # BGR pixel at (x=200, y=100)
blue, green, red = img[100, 200]

# Vectorized access to a region (ROI)
roi = img[50:150, 100:300]      # rows 50-149, cols 100-299

Accès aux pixels et ROI

L'accès pixel par pixel via img[y, x] est lent et déconseillé dans les boucles — préférez toujours le slicing NumPy. .copy() quand vous affectez une ROI pour que les changements ultérieurs de la source ne s'y déversent pas. Modifier img[:, :, canal] est la façon la plus rapide d'agir sur un seul canal de couleur.

opencv
import cv2
import numpy as np

img = cv2.imread("photo.jpg")

# access a single pixel (slow)
b, g, r = img[100, 200]

# access a single channel faster
blue = img[100, 200, 0]
img[100, 200] = [255, 255, 255]   # set to white

# numpy slicing is much faster than item-by-item
roi = img[100:200, 200:400].copy()

# copy ROI to another location
img[0:100, 0:200] = roi

# modify a whole channel
img[:, :, 2] = 0   # zero out the red channel

Types de données et conversion

La plupart des fonctions OpenCV attendent du uint8 (0-255), mais des algorithmes comme SIFT, le flux optique et la détection de contours exigent souvent du float32. Ne castez jamais directement avec .astype() après une soustraction — le débordement uint8 transforme -1 en 255. Utilisez cv2.absdiff ou convertissez en float d'abord. Recastez toujours en uint8 avant cv2.imwrite / imshow.

opencv
import cv2
import numpy as np

img = cv2.imread("photo.jpg")      # uint8, 0-255
print(img.dtype, img.min(), img.max())   # uint8 0 255

# convert to float32 (0.0-1.0 for many algorithms)
f = img.astype(np.float32) / 255.0

# convert back to uint8 for display/save
u = (f * 255).astype(np.uint8)

# clamp then cast (avoid overflow when subtracting)
diff = cv2.absdiff(img, img)       # safe subtraction
print(diff.dtype)                  # uint8

# CV_32F / CV_64F / CV_8U constants (used in some functions)
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
print(gray.dtype)                  # uint8
02

Capture vidéo

Ouvrir la webcam

VideoCapture(0) ouvre la webcam par défaut ; utilisez 1, 2... pour les caméras additionnelles. Appelez toujours cap.release() pour libérer l'appareil — l'oublier peut laisser la caméra occupée pour les autres apps. waitKey(1) attend ~1 ms ; l'astuce & 0xFF assure la compatibilité sur les systèmes 64 bits où waitKey retourne plus de 8 bits.

opencv
import cv2

cap = cv2.VideoCapture(0)           # 0 = default camera
print(cap.isOpened())              # True if camera opened

while True:
    ret, frame = cap.read()        # ret is False at end of stream
    if not ret:
        break

    gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)
    cv2.imshow("frame", gray)

    if cv2.waitKey(1) & 0xFF == ord('q'):
        break

cap.release()
cv2.destroyAllWindows()

Lire un fichier vidéo

CAP_PROP_FRAME_COUNT est souvent approximatif et peu fiable pour certains codecs — ne vous y fiez pas pour un seek exact. waitKey(int(1000/fps)) joue à peu près à la bonne vitesse ; pour un timing précis, utilisez une vraie horloge. Certaines vidéos compressées ne s'ouvrent pas sans le bon backend (FFmpeg).

opencv
import cv2

cap = cv2.VideoCapture("movie.mp4")

# video properties
fps    = cap.get(cv2.CAP_PROP_FPS)
width  = cap.get(cv2.CAP_PROP_FRAME_WIDTH)
height = cap.get(cv2.CAP_PROP_FRAME_HEIGHT)
count  = cap.get(cv2.CAP_PROP_FRAME_COUNT)
print(f"{width}x{height} @ {fps} fps, {count} frames")

while cap.isOpened():
    ret, frame = cap.read()
    if not ret:
        break
    cv2.imshow("video", frame)
    if cv2.waitKey(int(1000 / fps)) & 0xFF == ord('q'):
        break

cap.release()
cv2.destroyAllWindows()

Sauvegarder / écrire une vidéo

Le code FourCC dépend de la plateforme et du codec : 'mp4v' est très portable, 'XVID' produit du .avi, 'avc1' donne du H.264 (peut être indisponible sans codecs propriétaires). La taille de trame passée à VideoWriter DOIT matcher les trames écrites, sinon le fichier est corrompu. Appelez toujours out.release() pour flusher et fermer le fichier.

opencv
import cv2

cap = cv2.VideoCapture(0)
fourcc = cv2.VideoWriter_fourcc(*'mp4v')   # or 'XVID', 'avc1'
fps = 20.0
size = (640, 480)
out = cv2.VideoWriter("out.mp4", fourcc, fps, size)

while cap.isOpened():
    ret, frame = cap.read()
    if not ret:
        break
    frame = cv2.resize(frame, size)
    out.write(frame)
    cv2.imshow("rec", frame)
    if cv2.waitKey(1) & 0xFF == ord('q'):
        break

cap.release()
out.release()
cv2.destroyAllWindows()

Réglages de la caméra

Les propriétés de caméra dépendent du matériel et du driver — beaucoup de webcams ignorent en silence les réglages non supportés ou calent sur la valeur valide la plus proche, donc relisez toujours la valeur réelle. CAP_PROP_EXPOSURE utilise log2 des secondes (-4 = 1/16 s). L'auto-exposition doit être désactivée (mise à 1) pour que l'exposition manuelle prenne effet sur la plupart des caméras.

opencv
import cv2

cap = cv2.VideoCapture(0)

# set resolution
cap.set(cv2.CAP_PROP_FRAME_WIDTH, 1280)
cap.set(cv2.CAP_PROP_FRAME_HEIGHT, 720)

# set exposure / focus / brightness
cap.set(cv2.CAP_PROP_EXPOSURE, -4)      # log2 exposure time
cap.set(cv2.CAP_PROP_BRIGHTNESS, 128)
cap.set(cv2.CAP_PROP_AUTO_EXPOSURE, 1)  # 1=manual, 3=auto

# disable autofocus and set manual focus
cap.set(cv2.CAP_PROP_AUTOFOCUS, 0)
cap.set(cv2.CAP_PROP_FOCUS, 50)

print(cap.get(cv2.CAP_PROP_FRAME_WIDTH))   # actual width may differ

Fréquence d'images et timing

cap.get(CAP_PROP_FPS) retourne le FPS configuré, pas le taux réel de capture — mesurez avec une vraie horloge. Une moyenne mobile sur 30 trames lisse le jitter. Les plus gros tueurs de FPS sont cv2.imshow (thread GUI) et cv2.imwrite par trame ; pour benchmarker, désactivez l'affichage. Pour un timing déterministe, accumulez les trames dans un thread et traitez depuis une file.

opencv
import cv2
import time

cap = cv2.VideoCapture(0)
prev = time.time()
fps_hist = []

while True:
    ret, frame = cap.read()
    if not ret:
        break

    now = time.time()
    dt = now - prev
    prev = now
    if dt > 0:
        fps_hist.append(1.0 / dt)
        fps = sum(fps_hist[-30:]) / min(len(fps_hist), 30)
        cv2.putText(frame, f"FPS: {fps:.1f}", (10, 30),
                    cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 255, 0), 2)

    cv2.imshow("fps", frame)
    if cv2.waitKey(1) & 0xFF == ord('q'):
        break

cap.release()
cv2.destroyAllWindows()
03

Dessin

Ligne et rectangle

Toutes les fonctions de dessin mutent l'image en place — passez une copie pour garder l'original. Les coordonnées sont (x, y), l'inverse de l'indexation NumPy [y, x]. Les couleurs sont des tuples BGR. Utilisez thickness=-1 pour les formes pleines et cv2.LINE_AA pour des lignes lisses (anti-aliasées) sur les bords diagonaux.

opencv
import cv2
import numpy as np

img = np.zeros((400, 400, 3), dtype=np.uint8)

# line(img, pt1, pt2, color, thickness)
cv2.line(img, (10, 10), (390, 10), (0, 255, 0), 2)

# rectangle(img, pt1, pt2, color, thickness)
cv2.rectangle(img, (50, 50), (200, 150), (255, 0, 0), 3)

# filled rectangle (thickness = -1)
cv2.rectangle(img, (220, 50), (370, 150), (0, 0, 255), -1)

# anti-aliased line (cv2.LINE_AA)
cv2.line(img, (10, 380), (390, 200), (255, 255, 0), 1, cv2.LINE_AA)

cv2.imshow("img", img)
cv2.waitKey(0)

Cercle et ellipse

Le paramètre axes d'ellipse est (demiLargeur, demiHauteur) — la largeur pleine vaut 2 * axes[0]. angle pivote toute l'ellipse ; startAngle/endAngle dessinent des arcs partiels (0° = droite, sens antihoraire). Dessiner des arcs partiels est la façon standard de rendre des parts de camembert ou des indicateurs de direction de mouvement.

opencv
import cv2
import numpy as np

img = np.zeros((400, 400, 3), dtype=np.uint8)

# circle(img, center, radius, color, thickness)
cv2.circle(img, (100, 100), 50, (0, 255, 255), 3)
cv2.circle(img, (300, 100), 50, (255, 0, 255), -1)   # filled

# ellipse(img, center, axes, angle, startAngle, endAngle, color, thickness)
cv2.ellipse(img, (200, 250), (100, 50), 30, 0, 360, (0, 255, 0), 2)

# partial arc (0 to 180 degrees)
cv2.ellipse(img, (200, 250), (100, 50), 30, 0, 180, (0, 0, 255), 3)

cv2.imshow("img", img)
cv2.waitKey(0)

Polygone et polylignes

polylines accepte une liste de tableaux de points, donc plusieurs polygones en un appel. Le tableau de points doit être int32 et reformé en (-1, 1, 2). Utilisez fillPoly pour les formes pleines ; pour des remplissages translucides, dessinez sur un overlay et mélangez avec addWeighted. Le flag isClosed relie le dernier point au premier.

opencv
import cv2
import numpy as np

img = np.zeros((400, 400, 3), dtype=np.uint8)

# polygon points: shape (N, 1, 2), int32
pts = np.array([[50, 50], [200, 30], [350, 200],
                [300, 350], [80, 300]], dtype=np.int32)
pts = pts.reshape((-1, 1, 2))

# outline only (not closed)
cv2.polylines(img, [pts], False, (0, 255, 0), 2)

# closed polygon outline
cv2.polylines(img, [pts], True, (255, 0, 0), 3)

# filled polygon
cv2.fillPoly(img, [pts], (0, 0, 255))

cv2.imshow("img", img)
cv2.waitKey(0)

Texte

Les polices intégrées d'OpenCV sont des polices vectorielles Hershey — elles ne supportent pas les caractères CJK/chinois. Pour du texte non latin, rendez avec PIL (Pillow) ImageFont et reconvertissez, ou utilisez cv2.freetype d'opencv-contrib. getTextSize retourne ((largeur, hauteur), baseline) — utile pour centrer le texte ou dessiner un fond derrière.

opencv
import cv2
import numpy as np

img = np.zeros((300, 600, 3), dtype=np.uint8)

# putText(img, text, org, fontFace, fontScale, color, thickness)
cv2.putText(img, "Hello OpenCV", (10, 50),
            cv2.FONT_HERSHEY_SIMPLEX, 1.2, (255, 255, 255), 2)

# fonts
fonts = [cv2.FONT_HERSHEY_SIMPLEX, cv2.FONT_HERSHEY_PLAIN,
         cv2.FONT_HERSHEY_DUPLEX, cv2.FONT_HERSHEY_COMPLEX,
         cv2.FONT_HERSHEY_TRIPLEX, cv2.FONT_ITALIC]
for i, f in enumerate(fonts):
    cv2.putText(img, f"font {i}", (10, 100 + i*30), f, 0.8, (0, 255, 0), 1)

# measure text size before drawing
(text_w, text_h), baseline = cv2.getTextSize(
    "Measured", cv2.FONT_HERSHEY_SIMPLEX, 1.0, 2)
cv2.rectangle(img, (10, 260), (10 + text_w, 260 + text_h + baseline),
              (0, 0, 255), 1)

Flèche et marqueur

Le tipLength d'arrowedLine est une fraction de la longueur de ligne, donc les flèches longues ont des pointes proportionnellement plus grandes — réglez-le explicitement pour des pointes de taille constante. drawMarker est pratique pour mettre en valeur des points clés (ex. caractéristiques détectées ou coins) ; MARKER_TILTED_CROSS donne un marqueur en X.

opencv
import cv2
import numpy as np

img = np.zeros((400, 400, 3), dtype=np.uint8)

# arrowedLine(img, pt1, pt2, color, thickness, tipLength)
cv2.arrowedLine(img, (50, 50), (350, 50), (0, 255, 0), 2, tipLength=0.05)
cv2.arrowedLine(img, (200, 200), (200, 380), (0, 0, 255), 3, tipLength=0.1)

# drawMarker (cross, tilted cross, circle, square, diamond)
cv2.drawMarker(img, (100, 300), (255, 0, 255),
               markerType=cv2.MARKER_CROSS, markerSize=30, thickness=2)
cv2.drawMarker(img, (300, 300), (255, 255, 0),
               markerType=cv2.MARKER_DIAMOND, markerSize=30, thickness=2)

cv2.imshow("img", img)
cv2.waitKey(0)

Overlay et annotation

La technique d'overlay (dessiner sur une copie, puis addWeighted) est la façon standard de dessiner des remplissages translucides — OpenCV n'a pas d'alpha natif pour les formes. Dessinez toujours le texte plein APRÈS le mélange pour qu'il reste net ; le dessiner sur l'overlay avant le mélange le rend flou. Ce motif est partout dans la visualisation de détection/segmentation.

opencv
import cv2
import numpy as np

img = cv2.imread("photo.jpg")
overlay = img.copy()

# draw a translucent rectangle on the overlay
cv2.rectangle(overlay, (50, 50), (250, 150), (0, 0, 255), -1)
cv2.putText(overlay, "REGION", (60, 110),
            cv2.FONT_HERSHEY_SIMPLEX, 1, (255, 255, 255), 2)

# blend overlay onto the original (alpha=0.4)
out = cv2.addWeighted(overlay, 0.4, img, 0.6, 0)

cv2.imshow("out", out)
cv2.waitKey(0)
04

Arithmétique d'images

Addition et soustraction

Le cv2.add d'OpenCV sature à 255 (250 + 10 = 255), tandis que le + de NumPy boucle (250 + 10 = 8 à cause du débordement uint8). Pour les images, utilisez toujours cv2.add / cv2.subtract — le bouclage crée des artefacts visibles noir/blanc. absdiff est le cheval de bataille de la soustraction de fond et de la détection de mouvement.

opencv
import cv2
import numpy as np

a = cv2.imread("a.jpg")
b = cv2.imread("b.jpg")
b = cv2.resize(b, (a.shape[1], a.shape[0]))   # match sizes

# OpenCV addition: saturated (caps at 255)
add_cv = cv2.add(a, b)

# NumPy addition: wraps around (250 + 10 = 264 -> 8)
add_np = a + b

# subtract (saturated, never goes below 0)
sub = cv2.subtract(a, b)

# absolute difference (handy for motion detection)
diff = cv2.absdiff(a, b)

Mélange et AddWeighted

addWeighted exige des images de taille et dtype identiques — redimensionnez d'abord. Le terme gamma ajoute une constante à chaque pixel, utile pour la luminosité. Le fondu enchaîné classique entre deux images est juste addWeighted avec alpha balayant de 0 à 1.

opencv
import cv2
import numpy as np

a = cv2.imread("a.jpg")
b = cv2.imread("b.jpg")
b = cv2.resize(b, (a.shape[1], a.shape[0]))

# dst = alpha * a + beta * b + gamma
blend = cv2.addWeighted(a, 0.7, b, 0.3, 0)

# brighten by adding a constant (gamma)
bright = cv2.addWeighted(a, 1.0, a, 0.0, 50)

# fade between two images over N steps
for i in range(11):
    alpha = i / 10.0
    frame = cv2.addWeighted(a, alpha, b, 1 - alpha, 0)
    cv2.imshow("fade", frame)
    cv2.waitKey(200)

Opérations bit à bit

Les opérations bit à bit sont la façon standard d'appliquer un masque : cv2.bitwise_or(src, dst, mask=mask) copie src dans dst seulement là où le masque est non nul. Le masque doit être une image 8 bits mono-canal où non nul signifie « garder ». C'est le socle de l'extraction de ROI et du remplacement de fond.

opencv
import cv2
import numpy as np

a = np.zeros((200, 200), dtype=np.uint8)
cv2.rectangle(a, (20, 20), (120, 120), 255, -1)

b = np.zeros((200, 200), dtype=np.uint8)
cv2.circle(b, (100, 100), 60, 255, -1)

# bitwise AND / OR / XOR / NOT
and_ = cv2.bitwise_and(a, b)
or_  = cv2.bitwise_or(a, b)
xor  = cv2.bitwise_xor(a, b)
not_ = cv2.bitwise_not(a)

# use a mask to copy only part of an image
mask = np.zeros((200, 200), dtype=np.uint8)
cv2.circle(mask, (100, 100), 50, 255, -1)
src = np.full((200, 200, 3), (0, 255, 0), dtype=np.uint8)
dst = cv2.imread("photo.jpg")
dst = cv2.resize(dst, (200, 200))
result = cv2.bitwise_or(src, dst, mask=mask)

Différence d'images et mouvement

La différence de trames est le détecteur de mouvement le plus simple : seuillez la différence absolue entre trames consécutives. Elle échoue si la caméra bouge et ignore le mouvement lent — pour de vrais systèmes, utilisez la soustraction de fond (cv2.createBackgroundSubtractorMOG2) ou le flux optique. L'ouverture morphologique retire le bruit ; la dilatation fusionne les blobs proches.

opencv
import cv2
import numpy as np

prev = cv2.imread("frame1.jpg", cv2.IMREAD_GRAYSCALE)
curr = cv2.imread("frame2.jpg", cv2.IMREAD_GRAYSCALE)

# absolute difference
diff = cv2.absdiff(prev, curr)

# threshold to get a binary motion mask
_, mask = cv2.threshold(diff, 25, 255, cv2.THRESH_BINARY)

# clean up with morphology
kernel = np.ones((5, 5), np.uint8)
mask = cv2.morphologyEx(mask, cv2.MORPH_OPEN, kernel)
mask = cv2.dilate(mask, kernel, iterations=2)

# find moving contours
contours, _ = cv2.findContours(mask, cv2.RETR_EXTERNAL,
                               cv2.CHAIN_APPROX_SIMPLE)
for c in contours:
    if cv2.contourArea(c) > 500:
        x, y, w, h = cv2.boundingRect(c)
        cv2.rectangle(curr, (x, y), (x+w, y+h), (0, 255, 0), 2)

ROI et masquage

bitwise_and avec un masque est la façon idiomatique d'extraire des régions irrégulières. L'indexation booléenne NumPy (img[mask]) est plus flexible mais retourne un tableau plat de pixels, pas une image formée. Faites toujours .copy() des ROI que vous comptez réutiliser — le slicing retourne une vue aliasant l'original.

opencv
import cv2
import numpy as np

img = cv2.imread("photo.jpg")
h, w = img.shape[:2]

# build a mask: white circle on black background
mask = np.zeros((h, w), dtype=np.uint8)
cv2.circle(mask, (w // 2, h // 2), 150, 255, -1)

# keep only the masked region, zero elsewhere
masked = cv2.bitwise_and(img, img, mask=mask)

# extract ROI by bounding box
roi = img[100:300, 200:500].copy()

# put ROI back (or to a different location)
img[0:200, 0:300] = roi

# boolean mask (NumPy) — also works, but converts to 0/255
bool_mask = np.zeros((h, w), dtype=bool)
bool_mask[100:300, 200:500] = True
img_masked = img.copy()
img_masked[~bool_mask] = 0

Saturation vs bouclage

Le piège du débordement uint8 : NumPy boucle (300 -> 44), OpenCV sature (300 -> 255). Pour toute arithmétique pouvant dépasser 0-255, utilisez cv2.add/subtract ou promettez en int16/float32 d'abord puis clippez. Mêler des opérations cv2 et NumPy dans le même pipeline est la source n°1 des artefacts mystérieux de pixels sombres/lumineux.

opencv
import cv2
import numpy as np

img = cv2.imread("photo.jpg")

# WRONG: NumPy arithmetic wraps around (200 + 100 -> 44)
bad = img + 100

# RIGHT: cv2.add saturates at 255 (200 + 100 -> 255)
good = cv2.add(img, np.full_like(img, 100))

# subtracting a bright image: cv2 clamps to 0
dark = cv2.subtract(img, np.full_like(img, 100))

# manual saturation (equivalent to cv2.add)
manual = np.clip(img.astype(np.int16) + 100, 0, 255).astype(np.uint8)

# mixing cv2 and numpy is a common bug source:
# half = img // 2          # NumPy: fine (no overflow)
# half_then_add = half + half   # might equal original (ok)
# but bright = img + img  # wraps! 150+150=300 -> 44
05

Transformations géométriques

Redimensionnement / mise à l'échelle

INTER_AREA est le meilleur pour la réduction (évite l'aliasing), INTER_CUBIC ou INTER_LINEAR pour l'agrandissement. INTER_NEAREST est le plus rapide mais créneaux — utilisé pour les images de labels/masques où il ne faut pas introduire de nouvelles valeurs de pixels. Le tuple dsize est (largeur, hauteur), l'inverse de img.shape qui est (hauteur, largeur).

opencv
import cv2

img = cv2.imread("photo.jpg")
h, w = img.shape[:2]

# resize to a fixed size
small = cv2.resize(img, (320, 240))

# resize by a scale factor (fx, fy)
big = cv2.resize(img, None, fx=2.0, fy=2.0)

# resize keeping aspect ratio
scale = 0.5
new = cv2.resize(img, (int(w * scale), int(h * scale)))

# interpolation methods
down = cv2.resize(img, (w // 2, h // 2),
                  interpolation=cv2.INTER_AREA)      # shrinking
up   = cv2.resize(img, (w * 2, h * 2),
                  interpolation=cv2.INTER_CUBIC)     # enlarging

Rotation

cv2.rotate est bien plus rapide que warpAffine pour les multiples de 90°. L'angle de getRotationMatrix2D est en degrés, positif = antihoraire. Pour pivoter sans rognage, recalculez la boîte englobante (new_w, new_h) et décalez la matrice de rotation — sinon les coins d'une grande image pivotée sont coupés.

opencv
import cv2

img = cv2.imread("photo.jpg")
h, w = img.shape[:2]

# rotate 90/180/270 (fast, no interpolation)
rot90  = cv2.rotate(img, cv2.ROTATE_90_CLOCKWISE)
rot180 = cv2.rotate(img, cv2.ROTATE_180)
rot270 = cv2.rotate(img, cv2.ROTATE_90_COUNTERCLOCKWISE)

# arbitrary-angle rotation
center = (w // 2, h // 2)
angle = 45
scale = 1.0
M = cv2.getRotationMatrix2D(center, angle, scale)
rot = cv2.warpAffine(img, M, (w, h))

# rotate and expand the canvas to fit the whole image
cos = abs(M[0, 0]); sin = abs(M[0, 1])
new_w = int(h * sin + w * cos)
new_h = int(h * cos + w * sin)
M[0, 2] += (new_w - w) / 2
M[1, 2] += (new_h - h) / 2
rot_fit = cv2.warpAffine(img, M, (new_w, new_h))

Transformation affine

Une transformation affine préserve parallélisme et rapports de distances — définie par 3 correspondances de points (6 degrés de liberté). warpAffine utilise un mapping avant implicite via lookup inverse, donc M mappe src->dst mais la fonction l'inverse en interne. Utilisez borderMode=BORDER_REFLECT ou BORDER_CONSTANT pour contrôler le remplissage hors limites.

opencv
import cv2
import numpy as np

img = cv2.imread("photo.jpg")
h, w = img.shape[:2]

# affine: parallel lines stay parallel (6 DOF)
src = np.float32([[50, 50], [200, 50], [50, 200]])
dst = np.float32([[10, 100], [200, 50], [100, 250]])
M = cv2.getAffineTransform(src, dst)
warped = cv2.warpAffine(img, M, (w, h))

# inverse mapping (destination -> source)
inv = cv2.invertAffineTransform(M)

# translation is a special affine
T = np.float32([[1, 0, 100], [0, 1, 50]])  # shift right 100, down 50
shifted = cv2.warpAffine(img, T, (w, h))

# black border is default; use borderMode for other fill
reflected = cv2.warpAffine(img, T, (w, h),
                           borderMode=cv2.BORDER_REFLECT)

Transformation perspective

La perspective (homographie) est définie par 4 paires de points non colinéaires — 8 DDL. C'est la transformation standard du « scanner de documents » : prenez les 4 coins d'une carte/papier sur la photo et warp vers un rectangle. getPerspectiveTransform exige exactement 4 points ; pour un ajustement surdéterminé, utilisez cv2.findHomography avec RANSAC.

opencv
import cv2
import numpy as np

img = cv2.imread("card.jpg")
h, w = img.shape[:2]

# 4 point correspondences define a perspective (homography)
src = np.float32([[73, 110], [320, 78], [380, 350], [40, 320]])
dst = np.float32([[0, 0], [w, 0], [w, h], [0, h]])

M = cv2.getPerspectiveTransform(src, dst)
warped = cv2.warpPerspective(img, M, (w, h))

# invert the homography to map back
M_inv = cv2.getPerspectiveTransform(dst, src)
restored = cv2.warpPerspective(warped, M_inv, (w, h))

Retournement et miroir

flip est une opération mémoire bon marché — bien plus rapide que warpAffine. Convention du flipCode : positif retourne horizontalement, 0 verticalement, négatif les deux. cv2.transpose échange les axes et sert parfois de rotation 90° rapide combinée à un flip.

opencv
import cv2

img = cv2.imread("photo.jpg")

# flip(img, flipCode)
#   0  -> vertical flip (around x-axis)  (upside-down)
#   1  -> horizontal flip (around y-axis) (mirror)
#  -1  -> both (180° rotation equivalent)
v = cv2.flip(img, 0)
h = cv2.flip(img, 1)
both = cv2.flip(img, -1)

# transpose (swap x and y axes) — like a 90° rotation + flip
t = cv2.transpose(img)

Remap (mapping personnalisé)

remap est la transformation géométrique la plus générale — resize, rotation et même correction de distorsion barrel/objectif s'expriment tous comme remap. Construisez toujours les maps avec vectorisation NumPy, pas de boucles Python (la version à boucles ci-dessus est illustrative — ~100x plus lente). INTER_LINEAR par défaut ; pour la précision sous-pixel sur les bords, INTER_CUBIC.

opencv
import cv2
import numpy as np

img = cv2.imread("photo.jpg")
h, w = img.shape[:2]

# build coordinate maps: map_x, map_y say where each output pixel comes from
map_x = np.zeros((h, w), dtype=np.float32)
map_y = np.zeros((h, w), dtype=np.float32)

for y in range(h):
    for x in range(w):
        # mirror the image
        map_x[y, x] = w - 1 - x
        map_y[y, x] = y

remapped = cv2.remap(img, map_x, map_y, cv2.INTER_LINEAR)

# vectorized version (much faster) — wave distortion
xs, ys = np.meshgrid(np.arange(w), np.arange(h))
map_x = xs.astype(np.float32) + 10 * np.sin(ys / 20.0)
map_y = ys.astype(np.float32) + 10 * np.cos(xs / 20.0)
wave = cv2.remap(img, map_x, map_y, cv2.INTER_LINEAR,
                 borderMode=cv2.BORDER_REFLECT)
06

Filtrage d'images

Flou moyen (box filter)

Le flou moyen est le filtre passe-bas le plus simple — il remplace chaque pixel par la moyenne de son voisinage. Les noyaux doivent être impairs et positifs. Des noyaux plus grands floutent plus mais détruisent le détail plus vite. Utilisez-le quand vous voulez spécifiquement une pondération uniforme ; pour les images naturelles, le flou gaussien est presque toujours meilleur.

opencv
import cv2

img = cv2.imread("photo.jpg")

# 3x3 box blur
blur3 = cv2.blur(img, (3, 3))

# larger kernel = more blur
blur9 = cv2.blur(img, (9, 9))

# boxFilter with normalized=False gives the sum (not average)
sum_ = cv2.boxFilter(img, -1, (5, 5), normalize=False)

# normalized=True is equivalent to cv2.blur
avg = cv2.boxFilter(img, -1, (5, 5), normalize=True)

Flou gaussien

Le flou gaussien est le noyau de lissage par défaut — il pondère les voisins selon une gaussienne, préservant mieux les contours que le filtre box. Si vous passez ksize=(0,0) et sigmaX, OpenCV calcule automatiquement la taille du noyau. Le flou gaussien est un prérequis avant Canny, le sous-échantillonnage et Laplacian pour supprimer l'amplification du bruit.

opencv
import cv2

img = cv2.imread("photo.jpg")

# GaussianBlur(img, ksize, sigmaX)
g = cv2.GaussianBlur(img, (5, 5), 0)

# specifying sigma explicitly
g2 = cv2.GaussianBlur(img, (5, 5), sigmaX=1.5, sigmaY=1.5)

# odd kernel size required; (0, 0) auto-derives sigma from ksize
g3 = cv2.GaussianBlur(img, (0, 0), sigmaX=2.0)

# Gaussian is the standard pre-processing step before edge detection
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
blurred = cv2.GaussianBlur(gray, (5, 5), 0)
edges = cv2.Canny(blurred, 50, 150)

Flou médian

Le flou médian est le filtre de référence contre le bruit poivre et sel (impulsionnel) — il remplace chaque pixel par la médiane de son voisinage, donc les valeurs aberrantes isolées sont retirées plutôt que propagées. Contrairement au gaussien, il préserve bien les contours. La taille du noyau doit être impaire. Plus lent que gaussien/box à cause du tri.

opencv
import cv2

img = cv2.imread("noisy.jpg")

# median blur — great for salt-and-pepper noise
m = cv2.medianBlur(img, 5)

# larger kernel removes more noise but blurs edges
m2 = cv2.medianBlur(img, 7)

# compared to Gaussian on the same image
g = cv2.GaussianBlur(img, (5, 5), 0)

Filtre bilatéral

Le filtrage bilatéral lisse les zones plates en gardant les contours nets — un filtre non linéaire préservant les contours qui pondère les voisins par proximité spatiale ET similarité de couleur. Bien plus lent que le gaussien (souvent 10x). L'application répétée est l'étape classique de « cartoonification » ; de grands sigmaColor mélangent sur plus de couleurs.

opencv
import cv2

img = cv2.imread("photo.jpg")

# bilateralFilter(img, d, sigmaColor, sigmaSpace)
#   d            = neighborhood diameter
#   sigmaColor   = how much colors can differ and still blend
#   sigmaSpace   = how far pixels influence each other (spatial)
b = cv2.bilateralFilter(img, d=9, sigmaColor=75, sigmaSpace=75)

# strong edge-preserving smoothing (cartoon effect)
b_strong = cv2.bilateralFilter(img, d=15, sigmaColor=150, sigmaSpace=150)

# repeat several times for a "cartoon / oil painting" look
cartoon = img.copy()
for _ in range(7):
    cartoon = cv2.bilateralFilter(cartoon, d=9, sigmaColor=75, sigmaSpace=75)

Netteté (noyau)

Les noyaux de netteté accentuent les hautes fréquences — mais amplifient aussi le bruit, donc appliquez-les après débruitage. Le noyau de netteté 3x3 classique somme à 1 (préserve la luminosité) ; une somme > 1 éclaircit. La technique du masque flou (soustraire une copie floue) est plus contrôlable et celle qu'utilisent réellement la plupart des éditeurs photo.

opencv
import cv2
import numpy as np

img = cv2.imread("photo.jpg")

# sharpening kernel: center boosts, neighbors subtracted
kernel = np.array([[ 0, -1,  0],
                   [-1,  5, -1],
                   [ 0, -1,  0]], dtype=np.float32)

sharp = cv2.filter2D(img, -1, kernel)

# stronger sharpening
kernel_strong = np.array([[-1, -1, -1],
                          [-1,  9, -1],
                          [-1, -1, -1]], dtype=np.float32)
sharp2 = cv2.filter2D(img, -1, kernel_strong)

# unsharp mask: image + (image - blurred) * amount
blur = cv2.GaussianBlur(img, (0, 0), 3)
unsharp = cv2.addWeighted(img, 1.5, blur, -0.5, 0)

Noyau personnalisé (filter2D)

filter2D applique un noyau de corrélation arbitraire — ddepth=-1 garde la profondeur source. Les noyaux peuvent être flottants pour des coefficients négatifs ; si le résultat devient négatif, passez ddepth=cv2.CV_16S ou CV_32F puis convertScaleAbs en retour. Les noyaux séparables (produit extérieur de noyaux 1D) sont bien plus rapides via sepFilter2D.

opencv
import cv2
import numpy as np

img = cv2.imread("photo.jpg")

# emboss kernel
emboss = np.array([[-2, -1,  0],
                   [-1,  1,  1],
                   [ 0,  1,  2]], dtype=np.float32)
out = cv2.filter2D(img, -1, emboss)

# edge enhance (Laplacian-like)
edge = np.array([[ 0,  1,  0],
                 [ 1, -4,  1],
                 [ 0,  1,  0]], dtype=np.float32)
edges = cv2.filter2D(img, -1, edge)

# box blur done manually
box = np.ones((5, 5), dtype=np.float32) / 25.0
blurred = cv2.filter2D(img, -1, box)

# separable filter (Gaussian) — faster than 2D
kx = cv2.getGaussianKernel(5, 1.0)         # 5x1
ky = cv2.getGaussianKernel(5, 1.0)         # 5x1
g2d = kx @ ky.T                            # 5x5
out2 = cv2.filter2D(img, -1, g2d)
07

Opérations morphologiques

Érosion et dilatation

L'érosion rétrécit les régions de premier plan (blanc) et retire les petites taches de bruit ; la dilatation les agrandit et comble les petits trous. La forme du noyau compte : RECT pour un usage général, ELLIPSE pour des formes plus rondes, CROSS pour amincir/relier le long des axes. iterations=N répète l'opération N fois, équivalent à un noyau plus grand.

opencv
import cv2
import numpy as np

img = cv2.imread("shape.png", cv2.IMREAD_GRAYSCALE)
_, binary = cv2.threshold(img, 127, 255, cv2.THRESH_BINARY)

kernel = np.ones((5, 5), np.uint8)

# erosion: shrinks white regions (removes small noise)
eroded = cv2.erode(binary, kernel, iterations=1)

# dilation: grows white regions (fills small holes)
dilated = cv2.dilate(binary, kernel, iterations=1)

# custom kernel shapes
rect = cv2.getStructuringElement(cv2.MORPH_RECT, (5, 5))
cross = cv2.getStructuringElement(cv2.MORPH_CROSS, (5, 5))
ellipse = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (5, 5))

Ouverture et fermeture

L'ouverture (érodé->dilaté) retire les petites taches claires sans changer la taille des objets plus grands. La fermeture (dilaté->érodé) comble les petits trous sombres. Elles sont idempotentes — appliquer deux fois égale une fois. Le motif de débruitage classique est fermer-puis-ouvrir (ou ouvrir-puis-fermer) pour traiter les deux types de défauts.

opencv
import cv2
import numpy as np

img = cv2.imread("noisy.png", cv2.IMREAD_GRAYSCALE)
_, binary = cv2.threshold(img, 127, 255, cv2.THRESH_BINARY)

kernel = np.ones((5, 5), np.uint8)

# opening = erode then dilate -> removes small foreground noise
opened = cv2.morphologyEx(binary, cv2.MORPH_OPEN, kernel)

# closing = dilate then erode -> fills small holes in foreground
closed = cv2.morphologyEx(binary, cv2.MORPH_CLOSE, kernel)

# typical denoise pipeline: open then close
clean = cv2.morphologyEx(binary, cv2.MORPH_CLOSE, kernel)
clean = cv2.morphologyEx(clean, cv2.MORPH_OPEN, kernel)

Gradient morphologique

Le gradient morphologique (dilatation - érosion) produit un contour épais des frontières d'objets — utile comme détecteur de contours rapide ou comme masque de segmentation. Contrairement à Canny, il donne des contours larges et remplis, donc bon pour mettre en valeur des régions plutôt que pour mesurer des positions exactes de contours.

opencv
import cv2
import numpy as np

img = cv2.imread("shape.png", cv2.IMREAD_GRAYSCALE)
_, binary = cv2.threshold(img, 127, 255, cv2.THRESH_BINARY)

kernel = np.ones((5, 5), np.uint8)

# gradient = dilation - erosion -> outlines of objects
gradient = cv2.morphologyEx(binary, cv2.MORPH_GRADIENT, kernel)

# on a grayscale image (works too)
gray_grad = cv2.morphologyEx(img, cv2.MORPH_GRADIENT, kernel)

Top hat et black hat

Le top-hat extrait les petites structures claires plus petites que le noyau (ex. texte sur document sombre) ; le black-hat extrait les petites structures sombres. Ensemble ils servent à l'extraction d'ombres/lumières et comme correcteur rapide d'éclairage inégal (l'astuce de division par le fond est courante dans les scanners de documents).

opencv
import cv2
import numpy as np

img = cv2.imread("photo.jpg", cv2.IMREAD_GRAYSCALE)

kernel = np.ones((15, 15), np.uint8)

# top hat = image - opening -> small bright features on dark bg
tophat = cv2.morphologyEx(img, cv2.MORPH_TOPHAT, kernel)

# black hat = closing - image -> small dark features on bright bg
blackhat = cv2.morphologyEx(img, cv2.MORPH_BLACKHAT, kernel)

# use case: correct uneven illumination
# background = large closing; divide image by background
bg = cv2.morphologyEx(img, cv2.MORPH_CLOSE, kernel)
corrected = cv2.divide(img, bg, scale=255)

Squelettisation

La squelettisation morphologique amincit une forme binaire en un axe médian d'un pixel — utile pour l'OCR, les empreintes et l'analyse de vaisseaux. La boucle itérative éroder-soustraire-ouvrir tourne jusqu'à vider l'image. En production, medial_axis ou thinning de scikit-image est plus rapide et plus propre.

opencv
import cv2
import numpy as np

img = cv2.imread("shape.png", cv2.IMREAD_GRAYSCALE)
_, img = cv2.threshold(img, 127, 255, cv2.THRESH_BINARY)

# skeleton via iterative morphological opening
kernel = np.ones((3, 3), np.uint8)
skeleton = np.zeros_like(img)

while True:
    eroded = cv2.erode(img, kernel)
    opened = cv2.morphologyEx(eroded, cv2.MORPH_OPEN, kernel)
    temp = cv2.subtract(eroded, opened)
    skeleton = cv2.bitwise_or(skeleton, temp)
    img = eroded
    if cv2.countNonZero(img) == 0:
        break

Hit-or-Miss

Hit-or-miss est le matcheur de motifs morphologique — il trouve des configurations exactes de pixels de premier plan et de fond, utile pour détecter des formes précises comme des coins ou des jonctions en T. Le noyau utilise 1 pour le premier plan requis, -1 pour le fond requis, 0 pour indifférent. Niché mais imbattable pour localiser un motif exact.

opencv
import cv2
import numpy as np

img = cv2.imread("pattern.png", cv2.IMREAD_GRAYSCALE)
_, binary = cv2.threshold(img, 127, 255, cv2.THRESH_BINARY)

# hit-or-miss finds exact patterns
# kernel encodes foreground (1), background (-1), don't-care (0)
kernel = np.array([[ 0,  1, -1],
                   [ 1, -1, -1],
                   [ 1,  1,  0]], dtype=np.int32)

hits = cv2.morphologyEx(binary, cv2.MORPH_HITMISS, kernel)

# count matching locations
ys, xs = np.where(hits > 0)
print(f"found {len(xs)} matches")
08

Détection de contours

Détecteur de contours Canny

Canny est le détecteur de contours le plus utilisé : lissage gaussien -> gradients de Sobel -> suppression des non-maxima -> hystérésis (deux seuils). Les pixels au-dessus du seuil haut sont des contours ; ceux entre bas et haut ne le sont que s'ils sont connectés à un contour fort. L'astuce des seuils auto (médiane × 0.7/1.3) marche bien sur images variées.

opencv
import cv2

img = cv2.imread("photo.jpg")
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
blurred = cv2.GaussianBlur(gray, (5, 5), 0)

# Canny(image, threshold1, threshold2, apertureSize, L2gradient)
edges = cv2.Canny(blurred, 50, 150)

# auto-tuned thresholds from the median intensity
v = np.median(blurred)
lower = int(max(0, 0.7 * v))
upper = int(min(255, 1.3 * v))
auto = cv2.Canny(blurred, lower, upper)

# L2 gradient (more accurate, slower)
edges_l2 = cv2.Canny(blurred, 50, 150, L2gradient=True)

Opérateur Sobel

Sobel calcule la dérivée première — utilisez ddepth=cv2.CV_64F (ou CV_16S) pour capturer les gradients négatifs, sinon le débordement uint8 rend invisibles les transitions sombre-vers-clair. ksize=3 standard ; ksize=5 donne des contours plus lisses mais plus larges. La magnitude (sqrt(sx²+sy²)) est le socle de Canny et de nombreux détecteurs de caractéristiques.

opencv
import cv2
import numpy as np

img = cv2.imread("photo.jpg", cv2.IMREAD_GRAYSCALE)

# Sobel x (vertical edges)
sx = cv2.Sobel(img, cv2.CV_64F, 1, 0, ksize=3)

# Sobel y (horizontal edges)
sy = cv2.Sobel(img, cv2.CV_64F, 0, 1, ksize=3)

# gradient magnitude
mag = np.sqrt(sx**2 + sy**2)
mag = np.uint8(255 * mag / mag.max())

# gradient direction (for non-max suppression)
angle = np.arctan2(sy, sx)

# convert back to visible uint8
sx_abs = cv2.convertScaleAbs(sx)
sy_abs = cv2.convertScaleAbs(sy)

Laplacian

Laplacian est la dérivée seconde — très sensible au bruit, donc toujours lisser d'abord. Il détecte les passages par zéro (changement de signe), donnant des contours fins et précis mais sans direction. Sert surtout à la détection de contours de Marr-Hildreth et comme canal 'L' dans la netteté d'image (masque flou). Utilisez CV_64F car la dérivée seconde plonge très en négatif.

opencv
import cv2
import numpy as np

img = cv2.imread("photo.jpg", cv2.IMREAD_GRAYSCALE)
blurred = cv2.GaussianBlur(img, (3, 3), 0)

# Laplacian: second derivative in both directions
lap = cv2.Laplacian(blurred, cv2.CV_64F)
lap_abs = cv2.convertScaleAbs(lap)

# zero-crossing detection (sharper edges)
# Manual Laplacian kernel
kernel = np.array([[0,  1, 0],
                   [1, -4, 1],
                   [0,  1, 0]], dtype=np.float32)
edges = cv2.filter2D(blurred, -1, kernel)

Filtre Scharr

Scharr est une variante de Sobel conçue pour les fenêtres 3x3 — quand un petit noyau s'impose, il donne une direction de gradient plus précise que Sobel ksize=3. Pour de plus grands noyaux (5x5, 7x7), Sobel convient. cv2.Sobel avec ksize=-1 équivaut à Scharr. Scharr est préféré quand la direction du gradient compte (HOG, orientation des contours).

opencv
import cv2
import numpy as np

img = cv2.imread("photo.jpg", cv2.IMREAD_GRAYSCALE)

# Scharr: a Sobel variant optimized for 3x3 kernels
# better rotational symmetry than 3x3 Sobel
sx = cv2.Scharr(img, cv2.CV_64F, 1, 0)
sy = cv2.Scharr(img, cv2.CV_64F, 0, 1)

mag = cv2.magnitude(sx, sy)
mag_u8 = cv2.convertScaleAbs(mag)

# equivalent to Sobel with ksize=-1
sx2 = cv2.Sobel(img, cv2.CV_64F, 1, 0, ksize=-1)

Pipeline de détection de contours

Le pipeline niveaux de gris -> débruitage -> Canny -> dilatation -> findContours couvre une énorme fraction des tâches de contours pratiques. La dilatation avant la recherche de contours referme les contours cassés qui sinon scindent un objet en plusieurs. Régler les seuils Canny et la taille du noyau de débruitage concentre l'essentiel de l'effort d'ingénierie.

opencv
import cv2
import numpy as np

img = cv2.imread("photo.jpg")

# 1. grayscale
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)

# 2. denoise (Gaussian or bilateral)
blurred = cv2.GaussianBlur(gray, (5, 5), 0)

# 3. auto-thresholded Canny
v = np.median(blurred)
edges = cv2.Canny(blurred, int(0.7 * v), int(1.3 * v))

# 4. dilate to close gaps, then find contours
edges = cv2.dilate(edges, np.ones((3, 3), np.uint8), iterations=1)
contours, _ = cv2.findContours(edges, cv2.RETR_EXTERNAL,
                               cv2.CHAIN_APPROX_SIMPLE)

# 5. filter by area
out = img.copy()
for c in contours:
    if cv2.contourArea(c) > 100:
        cv2.drawContours(out, [c], -1, (0, 255, 0), 2)

cv2.imshow("edges", edges)
cv2.imshow("contours", out)
cv2.waitKey(0)
09

Contours

Trouver les contours

findContours mute l'image source en OpenCV 3.x — passez une copie si vous avez besoin du binaire ensuite. RETR_EXTERNAL ne retourne que les contours les plus externes (le plus rapide) ; RETR_TREE donne la hiérarchie complète pour les formes imbriquées (trous dans les objets). CHAIN_APPROX_SIMPLE jette les points redondants le long des lignes droites, économisant la mémoire.

opencv
import cv2

img = cv2.imread("shapes.png")
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
_, binary = cv2.threshold(gray, 127, 255, cv2.THRESH_BINARY)

# findContours(image, mode, method)
# mode: RETR_EXTERNAL (outer only), RETR_LIST, RETR_TREE, RETR_CCOMP
# method: CHAIN_APPROX_SIMPLE compresses horizontal/vertical/diagonal segments
contours, hierarchy = cv2.findContours(binary, cv2.RETR_EXTERNAL,
                                       cv2.CHAIN_APPROX_SIMPLE)

print(f"found {len(contours)} contours")
# hierarchy is shape (1, N, 4): [next, prev, child, parent]

# OpenCV 3 returns (image, contours, hierarchy)
# OpenCV 4 returns (contours, hierarchy)

Dessiner les contours

drawContours(image, contours, contourIdx, couleur, épaisseur) : contourIdx=-1 dessine tous ; un index précis en dessine un. Thickness=-1 remplit le contour. Dessiner sur une image vierge est la façon standard de bâtir un masque de contours pour des opérations en aval comme la couleur moyenne ou un histogramme masqué.

opencv
import cv2

img = cv2.imread("shapes.png")
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
_, binary = cv2.threshold(gray, 127, 255, cv2.THRESH_BINARY)
contours, _ = cv2.findContours(binary, cv2.RETR_EXTERNAL,
                               cv2.CHAIN_APPROX_SIMPLE)

# draw all contours (-1), color, thickness
cv2.drawContours(img, contours, -1, (0, 255, 0), 2)

# draw a single contour by index
cv2.drawContours(img, contours, 0, (0, 0, 255), 3)

# filled contour (thickness = -1)
cv2.drawContours(img, contours, -1, (255, 0, 0), -1)

# draw on a blank canvas (mask)
mask = np.zeros_like(gray)
cv2.drawContours(mask, contours, -1, 255, -1)

Propriétés des contours

contourArea est en pixels et ignore les trous (utilisez le contour avec la hiérarchie RETR_CCOMP pour l'aire nette). Le dictionnaire des moments donne le centroïde (m10/m00, m01/m00) — protégez-vous de la division par zéro si m00 vaut 0 (contours dégénérés). Ratio d'aspect et étendue sont les descripteurs de forme les plus simples pour la classification de formes.

opencv
import cv2

img = cv2.imread("shapes.png")
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
_, binary = cv2.threshold(gray, 127, 255, cv2.THRESH_BINARY)
contours, _ = cv2.findContours(binary, cv2.RETR_EXTERNAL,
                               cv2.CHAIN_APPROX_SIMPLE)

for c in contours:
    area = cv2.contourArea(c)             # area in pixels
    peri = cv2.arcLength(c, True)         # perimeter (closed=True)
    M = cv2.moments(c)                     # spatial moments
    cx = int(M['m10'] / M['m00'])          # centroid x
    cy = int(M['m01'] / M['m00'])          # centroid y

    # bounding box
    x, y, w, h = cv2.boundingRect(c)
    aspect = w / float(h)                 # aspect ratio
    extent = area / float(w * h)          # filled area ratio

    print(f"area={area:.0f} peri={peri:.1f} center=({cx},{cy}) aspect={aspect:.2f}")

Rectangles englobants

boundingRect donne une boîte alignée aux axes (rapide, simple) ; minAreaRect donne le plus petit rectangle pivoté (utile pour mesurer l'orientation/taille réelle d'un objet). boxPoints convertit le rectangle pivoté en 4 coins transmissibles à drawContours. minEnclosingCircle est le plus petit cercle contenant le contour.

opencv
import cv2

img = cv2.imread("shapes.png")
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
_, binary = cv2.threshold(gray, 127, 255, cv2.THRESH_BINARY)
contours, _ = cv2.findContours(binary, cv2.RETR_EXTERNAL,
                               cv2.CHAIN_APPROX_SIMPLE)

for c in contours:
    # axis-aligned bounding rectangle
    x, y, w, h = cv2.boundingRect(c)
    cv2.rectangle(img, (x, y), (x+w, y+h), (0, 255, 0), 2)

    # minimum area (rotated) rectangle
    rect = cv2.minAreaRect(c)             # ((cx, cy), (w, h), angle)
    box = cv2.boxPoints(rect)             # 4 corner points
    box = np.int0(box)
    cv2.drawContours(img, [box], 0, (0, 0, 255), 2)

    # minimum enclosing circle
    (cx, cy), r = cv2.minEnclosingCircle(c)
    cv2.circle(img, (int(cx), int(cy)), int(r), (255, 0, 0), 2)

Approximation de contours

approxPolyDP simplifie un contour en polygone à moins de sommets avec l'algorithme de Douglas-Peucker. L'epsilon (typiquement 1-5 % du périmètre) contrôle la tolérance : plus petit garde plus de détail. Compter les sommets est le classifieur de formes artisanal classique — triangles=3, rectangles=4, cercles=beaucoup.

opencv
import cv2

img = cv2.imread("shapes.png")
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
_, binary = cv2.threshold(gray, 127, 255, cv2.THRESH_BINARY)
contours, _ = cv2.findContours(binary, cv2.RETR_EXTERNAL,
                               cv2.CHAIN_APPROX_SIMPLE)

for c in contours:
    peri = cv2.arcLength(c, True)
    # approxPolyDP: simplify the contour to fewer vertices
    eps = 0.04 * peri                      # 4% of perimeter
    approx = cv2.approxPolyDP(c, eps, True)

    n = len(approx)
    if n == 3:
        label = "triangle"
    elif n == 4:
        label = "rectangle"
    elif n == 5:
        label = "pentagon"
    else:
        label = f"{n}-gon"

    cv2.drawContours(img, [approx], -1, (0, 255, 0), 2)
    cv2.putText(img, label, tuple(approx[0][0]),
                cv2.FONT_HERSHEY_SIMPLEX, 0.6, (0, 0, 255), 2)

Enveloppe convexe et défauts

L'enveloppe convexe est la plus petite forme convexe englobant le contour — utile pour mesurer la compacité d'un objet et pour la détection de mains/doigts via les défauts de convexité. La profondeur de chaque défaut mesure à quel point le contour s'enfonce par rapport à l'enveloppe ; des défauts profonds sur une silhouette de main correspondent typiquement aux espaces entre les doigts.

opencv
import cv2

img = cv2.imread("hand.png")
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
_, binary = cv2.threshold(gray, 127, 255, cv2.THRESH_BINARY)
contours, _ = cv2.findContours(binary, cv2.RETR_EXTERNAL,
                               cv2.CHAIN_APPROX_SIMPLE)
c = max(contours, key=cv2.contourArea)

# convex hull (smallest convex polygon enclosing the contour)
hull = cv2.convexHull(c)
cv2.drawContours(img, [hull], -1, (0, 255, 0), 2)

# convexity defects (gaps between contour and hull) — needs returnPoints=False
hull_idx = cv2.convexHull(c, returnPoints=False)
defects = cv2.convexityDefects(c, hull_idx)
# defects[i] = (start, end, far, depth) — depth in 1/256 of peri

# is the contour convex?
is_convex = cv2.isContourConvex(c)
10

Seuillage

Seuillage simple

THRESH_BINARY : au-dessus->255, au-dessous->0. THRESH_TRUNC : au-dessus->plafonné à thresh, au-dessous->inchangé. THRESH_TOZERO : au-dessus->inchangé, au-dessous->0. Le ret retourné égale le seuil d'entrée pour le seuillage simple mais devient significatif pour Otsu/Triangle. Choisissez le type selon le traitement voulu des pixels hors plage.

opencv
import cv2

img = cv2.imread("doc.png", cv2.IMREAD_GRAYSCALE)

# threshold(src, thresh, maxval, type)
# returns (retval, binary_image)
ret, binary = cv2.threshold(img, 127, 255, cv2.THRESH_BINARY)

# threshold types
_, inv     = cv2.threshold(img, 127, 255, cv2.THRESH_BINARY_INV)
_, trunc   = cv2.threshold(img, 127, 255, cv2.THRESH_TRUNC)
_, tozero  = cv2.threshold(img, 127, 255, cv2.THRESH_TOZERO)
_, tozero_inv = cv2.threshold(img, 127, 255, cv2.THRESH_TOZERO_INV)

# ret is the threshold actually used (useful with Otsu)

Seuillage adaptatif

Le seuillage adaptatif calcule un seuil différent pour chaque pixel selon son voisinage local — essentiel pour les images à éclairage inégal (ex. photos de documents). blockSize doit être impair (typiquement 11-31) et plus grand que la taille des caractéristiques. C soustrait une constante à la moyenne locale ; augmentez-la pour supprimer le bruit à faible contraste.

opencv
import cv2

img = cv2.imread("doc.png", cv2.IMREAD_GRAYSCALE)
img = cv2.medianBlur(img, 5)

# adaptiveThreshold(src, maxValue, adaptiveMethod, thresholdType, blockSize, C)
# adaptiveMethod:
#   ADAPTIVE_THRESH_MEAN_C  -> mean of neighborhood minus C
#   ADAPTIVE_THRESH_GAUSSIAN_C -> weighted mean minus C
adap_mean = cv2.adaptiveThreshold(img, 255,
    cv2.ADAPTIVE_THRESH_MEAN_C, cv2.THRESH_BINARY, 11, 2)

adap_gauss = cv2.adaptiveThreshold(img, 255,
    cv2.ADAPTIVE_THRESH_GAUSSIAN_C, cv2.THRESH_BINARY, 11, 2)

Méthode d'Otsu

La méthode d'Otsu trouve le seuil global optimal en maximisant la variance entre classes de premier plan et de fond — passez thresh=0 et ajoutez le flag THRESH_OTSU. Flou d'abord toujours ; Otsu est sensible au bruit d'histogramme. La méthode Triangle marche mieux sur les images à un seul pic dominant (ex. microscopie). Le ret retourné est le seuil calculé.

opencv
import cv2

img = cv2.imread("doc.png", cv2.IMREAD_GRAYSCALE)
blurred = cv2.GaussianBlur(img, (5, 5), 0)

# Otsu: automatically picks the threshold that maximizes between-class variance
ret, otsu = cv2.threshold(blurred, 0, 255,
                          cv2.THRESH_BINARY + cv2.THRESH_OTSU)
print(f"Otsu threshold: {ret}")

# Triangle method (good for skewed histograms / single peak)
ret_t, tri = cv2.threshold(blurred, 0, 255,
                           cv2.THRESH_BINARY + cv2.THRESH_TRIANGLE)
print(f"Triangle threshold: {ret_t}")

Seuillage de couleur (inRange)

inRange est l'outil standard de segmentation par couleur — convertissez en HSV d'abord car il sépare la couleur (teinte) de la luminosité, rendant les seuils robustes aux changements d'éclairage. La teinte du rouge boucle sur 0/180, donc il faut deux masques en OU. Flou toujours avant inRange pour réduire les mouchetures de bruit dans le masque.

opencv
import cv2
import numpy as np

img = cv2.imread("photo.jpg")
hsv = cv2.cvtColor(img, cv2.COLOR_BGR2HSV)

# detect a range of green pixels
lower = np.array([35, 50, 50])
upper = np.array([85, 255, 255])
mask = cv2.inRange(hsv, lower, upper)

# apply mask to the original
result = cv2.bitwise_and(img, img, mask=mask)

# hue wraps around for red (0-10 and 170-180)
mask1 = cv2.inRange(hsv, np.array([0, 50, 50]),   np.array([10, 255, 255]))
mask2 = cv2.inRange(hsv, np.array([170, 50, 50]), np.array([180, 255, 255]))
red_mask = cv2.bitwise_or(mask1, mask2)

Pipeline de seuillage

Le pipeline débruitage -> seuillage -> morphologie gère la plupart des tâches de binarisation. Otsu pour un éclairage uniforme, adaptatif pour un éclairage inégal. La fermeture-puis-ouverture morphologique retire à la fois les trous intérieurs et les taches extérieures. Inspectez toujours le masque binaire — les paramètres de seuillage sont presque toujours spécifiques à l'image et exigent un réglage par jeu de données.

opencv
import cv2
import numpy as np

img = cv2.imread("doc.jpg")
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)

# 1. denoise
blurred = cv2.GaussianBlur(gray, (5, 5), 0)

# 2. choose a method
#    - flat lighting    -> Otsu
#    - uneven lighting  -> adaptive
#    - document scan    -> adaptive Gaussian
if lighting == "flat":
    _, binary = cv2.threshold(blurred, 0, 255,
                              cv2.THRESH_BINARY + cv2.THRESH_OTSU)
else:
    binary = cv2.adaptiveThreshold(blurred, 255,
        cv2.ADAPTIVE_THRESH_GAUSSIAN_C, cv2.THRESH_BINARY, 21, 5)

# 3. morphology cleanup
kernel = np.ones((3, 3), np.uint8)
binary = cv2.morphologyEx(binary, cv2.MORPH_CLOSE, kernel)
binary = cv2.morphologyEx(binary, cv2.MORPH_OPEN, kernel)

Binarisation pour l'OCR

Pour l'OCR, l'adaptatif gaussien bat presque toujours l'Otsu global sur les documents photographiés à cause de l'éclairage inégal. Accordez blockSize à la hauteur des caractères (règle empirique : 1-2× la largeur du trait × 4). La plupart des moteurs OCR (Tesseract) préfèrent du texte noir sur fond blanc — inversez si votre binaire est l'opposé.

opencv
import cv2

img = cv2.imread("text.png", cv2.IMREAD_GRAYSCALE)

# adaptive Gaussian with a block size matched to character height
# (e.g. char ~25 px -> blockSize ~31)
binary = cv2.adaptiveThreshold(img, 255,
    cv2.ADAPTIVE_THRESH_GAUSSIAN_C, cv2.THRESH_BINARY, 31, 10)

# invert if needed (OCR often prefers black-on-white)
binary_inv = cv2.bitwise_not(binary)

# Otsu on a preprocessed image as an alternative
blur = cv2.GaussianBlur(img, (3, 3), 0)
_, otsu = cv2.threshold(blur, 0, 255,
                        cv2.THRESH_BINARY_INV + cv2.THRESH_OTSU)
11

Espaces colorimétriques

BGR / RGB / gris

OpenCV lit les images en BGR par défaut ; la plupart des autres bibliothèques (matplotlib, PIL, scikit-image) utilisent RGB. Oublier cvtColor est la cause la plus fréquente des images « rouge et bleu inversés ». La conversion en niveaux de gris utilise des poids perceptuels (Y = 0.299R + 0.587G + 0.114B), pas une simple moyenne.

opencv
import cv2

bgr = cv2.imread("photo.jpg")           # OpenCV default: BGR

# BGR -> RGB (for matplotlib, PIL, etc.)
rgb = cv2.cvtColor(bgr, cv2.COLOR_BGR2RGB)

# BGR -> grayscale (luminance-weighted)
gray = cv2.cvtColor(bgr, cv2.COLOR_BGR2GRAY)

# RGB -> BGR (reverse)
bgr2 = cv2.cvtColor(rgb, cv2.COLOR_RGB2BGR)

# grayscale -> BGR (replicates channel, color image with no color)
bgr_from_gray = cv2.cvtColor(gray, cv2.COLOR_GRAY2BGR)

BGR vers HSV

Le HSV d'OpenCV utilise H dans 0-179 (pas 0-360) pour tenir dans un uint8 — source fréquente de bugs de facteur 2 en portant du code d'autres bibliothèques. S et V vont de 0 à 255. HSV est l'espace de référence pour la segmentation par couleur car la teinte est grossièrement invariante à la luminosité — utilisez-le pour le suivi d'objets par couleur.

opencv
import cv2
import numpy as np

bgr = cv2.imread("photo.jpg")
hsv = cv2.cvtColor(bgr, cv2.COLOR_BGR2HSV)

# split channels
h, s, v = cv2.split(hsv)

# HSV ranges in OpenCV: H: 0-179, S: 0-255, V: 0-255
# (H is halved so it fits in 8-bit — full hue circle is 0-360)
print(h.max(), s.max(), v.max())   # 179 255 255

# back to BGR
bgr2 = cv2.cvtColor(hsv, cv2.COLOR_HSV2BGR)

BGR vers LAB

CIELAB approche la perception humaine — des changements numériques égaux paraissent grossièrement également différents, d'où son usage pour les métriques de différence de couleur (ΔE). Le canal L encode la seule luminosité, donc éditer L est la façon la plus propre d'éclaircir une image sans décaler les couleurs. Le LAB d'OpenCV utilise 0-255 pour tous les canaux, pas le 0-100 standard de L.

opencv
import cv2

bgr = cv2.imread("photo.jpg")

# BGR -> LAB (perceptually uniform color space)
lab = cv2.cvtColor(bgr, cv2.COLOR_BGR2LAB)
L, A, B = cv2.split(lab)

# L: lightness (0-255), A: green<->red, B: blue<->yellow
# useful for separating luminance from color

# LAB is great for color-difference metrics (delta-E)
# and for editing lightness without affecting color
import numpy as np
lab_bright = lab.copy()
lab_bright[:, :, 0] = np.clip(lab_bright[:, :, 0].astype(int) + 30, 0, 255)
bgr_bright = cv2.cvtColor(lab_bright, cv2.COLOR_LAB2BGR)

Suivi de couleur (HSV)

Le suivi par couleur basé HSV est le plus simple des trackers d'objets — prenez la plage de teinte, seuillez, trouvez le plus gros blob. Il échoue sous mauvais éclairage (faible saturation), avec des objets de fond de couleur similaire et sur surfaces réfléchissantes. Pour un suivi robuste, combinez avec camshift/meanshift (rétroprojection d'un histogramme de teinte) ou un filtre de Kalman pour lisser le mouvement.

opencv
import cv2
import numpy as np

cap = cv2.VideoCapture(0)

while True:
    ret, frame = cap.read()
    if not ret:
        break

    hsv = cv2.cvtColor(frame, cv2.COLOR_BGR2HSV)

    # track a blue object
    lower = np.array([100, 80, 80])
    upper = np.array([130, 255, 255])
    mask = cv2.inRange(hsv, lower, upper)

    # find the largest blob
    contours, _ = cv2.findContours(mask, cv2.RETR_EXTERNAL,
                                   cv2.CHAIN_APPROX_SIMPLE)
    if contours:
        c = max(contours, key=cv2.contourArea)
        if cv2.contourArea(c) > 500:
            (x, y), r = cv2.minEnclosingCircle(c)
            cv2.circle(frame, (int(x), int(y)), int(r), (0, 255, 255), 2)

    cv2.imshow("frame", frame)
    cv2.imshow("mask", mask)
    if cv2.waitKey(1) & 0xFF == ord('q'):
        break

cap.release()

Séparer et fusionner les canaux

split/merge sont pratiques mais plus lents que l'indexation NumPy — img[:, :, 0] est le canal bleu et le modifier est plus rapide que split. Passez toujours les canaux à merge dans le bon ordre pour votre espace cible. L'astuce « mettre à zéro deux canaux » est la façon classique de visualiser la contribution d'un seul canal de couleur.

opencv
import cv2
import numpy as np

img = cv2.imread("photo.jpg")

# split into B, G, R channels (each is a 2-D array)
b, g, r = cv2.split(img)

# merge channels back (order matters!)
merged = cv2.merge([b, g, r])

# zero out one channel to visualize
zeros = np.zeros_like(b)
blue_only  = cv2.merge([b, zeros, zeros])
green_only = cv2.merge([zeros, g, zeros])
red_only   = cv2.merge([zeros, zeros, r])

# swap channels (e.g. fake RGB->BGR by swapping R and B)
swapped = cv2.merge([r, g, b])

Autres espaces colorimétriques

YCrCb sépare la luminance (Y) de la chrominance (Cr, Cb) — le socle de la compression JPEG et MPEG qui jette le détail de chrominance car l'humain est moins sensible à la couleur qu'à la luminosité. HLS diffère de HSV en ce que le blanc est à L=1 quelle que soit la saturation, rendant HLS meilleur pour certains effets d'ombrage. Choisissez l'espace qui rend votre opération invariante à ce dont vous ne vous souciez pas.

opencv
import cv2

bgr = cv2.imread("photo.jpg")

# YCrCb (used in JPEG compression)
ycrcb = cv2.cvtColor(bgr, cv2.COLOR_BGR2YCrCb)

# HLS (Hue, Lightness, Saturation — alternative to HSV)
hls = cv2.cvtColor(bgr, cv2.COLOR_BGR2HLS)

# YUV (used in video encoding)
yuv = cv2.cvtColor(bgr, cv2.COLOR_BGR2YUV)

# grayscale -> all spaces start from BGR, so chain conversions
gray_from_ycrcb = cv2.cvtColor(ycrcb, cv2.COLOR_YCrCb2BGR)
gray = cv2.cvtColor(gray_from_ycrcb, cv2.COLOR_BGR2GRAY)
12

Histogrammes

Calculer un histogramme

calcHist prend une liste d'images, une liste de canaux, un masque optionnel (None = toute l'image), le nombre de bins et la plage de valeurs. Pour des histogrammes multidimensionnels (ex. 2-D teinte-saturation), passez deux canaux et deux tailles de bins — utilisé dans la rétroprojection d'histogramme pour le suivi par couleur. L'histogramme de chaque canal est calculé indépendamment.

opencv
import cv2
import numpy as np

img = cv2.imread("photo.jpg", cv2.IMREAD_GRAYSCALE)

# calcHist(images, channels, mask, histSize, ranges)
hist = cv2.calcHist([img], [0], None, [256], [0, 256])
print(hist.shape)   # (256, 1)

# normalize to 0-1
hist /= hist.sum()

# multi-channel histogram (color)
bgr = cv2.imread("photo.jpg")
colors = ('b', 'g', 'r')
for i, col in enumerate(colors):
    h = cv2.calcHist([bgr], [i], None, [256], [0, 256])

Tracer un histogramme

Matplotlib est le moyen le plus simple de visualiser les histogrammes — mais convertissez BGR en RGB pour les couleurs de la légende, sinon les couleurs de votre tracé ne correspondront pas aux labels des canaux. Un histogramme penché à gauche est une image sombre, à droite une claire ; un pic étroit signifie faible contraste. Utilisez cela pour diagnostiquer exposition et balance des blancs.

opencv
import cv2
import numpy as np
import matplotlib.pyplot as plt

img = cv2.imread("photo.jpg")
colors = ('b', 'g', 'r')
for i, col in enumerate(colors):
    hist = cv2.calcHist([img], [i], None, [256], [0, 256])
    plt.plot(hist, color=col)
    plt.xlim([0, 256])

plt.title("Color Histogram")
plt.xlabel("Pixel value")
plt.ylabel("Frequency")
plt.show()

Égalisation d'histogramme

L'égalisation d'histogramme étire les intensités des pixels pour utiliser toute la plage 0-255 — parfait pour les images à faible contraste mais peut brûler les hautes lumières et amplifier le bruit. N'égalisez JAMAIS les trois canaux BGR directement — cela décale les couleurs. Convertissez toujours vers un espace luminance/chrominance (YCrCb, LAB, HSV), égalisez la luminance et reconvertissez.

opencv
import cv2

img = cv2.imread("dark.jpg", cv2.IMREAD_GRAYSCALE)

# global histogram equalization
eq = cv2.equalizeHist(img)

# equalization on color images: convert to YCrCb, equalize Y only
bgr = cv2.imread("color.jpg")
ycrcb = cv2.cvtColor(bgr, cv2.COLOR_BGR2YCrCb)
ycrcb[:, :, 0] = cv2.equalizeHist(ycrcb[:, :, 0])
eq_color = cv2.cvtColor(ycrcb, cv2.COLOR_YCrCb2BGR)

CLAHE (égalisation adaptative)

CLAHE est l'alternative de qualité production à l'égalisation globale — il opère par petites tuiles donc marche sur les images à éclairage inégal, et clipLimit plafonne l'amplification de contraste pour éviter d'exploser le bruit. tileGridSize de 8x8 est le défaut ; des tuiles plus petites donnent plus d'adaptation locale. Le choix de référence en imagerie médicale et amélioration de documents.

opencv
import cv2

img = cv2.imread("dark.jpg", cv2.IMREAD_GRAYSCALE)

# CLAHE: Contrast Limited Adaptive Histogram Equalization
# equalizes small tiles, limiting amplification of noise
clahe = cv2.createCLAHE(clipLimit=2.0, tileGridSize=(8, 8))
enhanced = clahe.apply(img)

# on color: equalize the L channel of LAB
bgr = cv2.imread("color.jpg")
lab = cv2.cvtColor(bgr, cv2.COLOR_BGR2LAB)
clahe = cv2.createCLAHE(clipLimit=3.0, tileGridSize=(8, 8))
lab[:, :, 0] = clahe.apply(lab[:, :, 0])
enhanced_color = cv2.cvtColor(lab, cv2.COLOR_LAB2BGR)

Rétroprojection d'histogramme

La rétroprojection d'histogramme répond à « où les pixels ressemblent-ils à la distribution de couleurs de ma ROI ? ». Construisez un histogramme 2-D teinte-saturation depuis un échantillon, puis rétroporjetez sur une image cible pour obtenir une carte de probabilité. C'est le socle du suivi meanShift/camShift — bien plus robuste qu'une plage HSV fixe car il apprend la vraie distribution de couleurs de la cible.

opencv
import cv2
import numpy as np

img = cv2.imread("scene.jpg")
hsv = cv2.cvtColor(img, cv2.COLOR_BGR2HSV)

# take a small ROI of the target color (the object to track)
roi = hsv[100:150, 100:150]
roi_hist = cv2.calcHist([roi], [0, 1], None, [180, 256], [0, 180, 0, 256])
cv2.normalize(roi_hist, roi_hist, 0, 255, cv2.NORM_MINMAX)

# backproject: each pixel = probability of belonging to the ROI's color
backproj = cv2.calcBackProject([hsv], [0, 1], roi_hist, [0, 180, 0, 256], 1)

# denoise and threshold
disc = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (5, 5))
backproj = cv2.filter2D(backproj, -1, disc)
_, mask = cv2.threshold(backproj, 50, 255, cv2.THRESH_BINARY)

result = cv2.bitwise_and(img, img, mask=mask)
13

Détection de caractéristiques

Détecteur de coins de Harris

Harris détecte les coins en vérifiant si déplacer une petite fenêtre dans n'importe quelle direction cause un grand changement d'intensité — les coins changent dans toutes les directions, les contours dans une, les zones plates dans aucune. La sortie est une carte de réponse de coins ; seuillez relativement au max (ex. 0.01 * max). blockSize est le voisinage pour le calcul du tenseur de structure.

opencv
import cv2
import numpy as np

img = cv2.imread("chessboard.jpg")
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)

# cornerHarris(gray, blockSize, ksize, k)
# blockSize: neighborhood for corner detection
# ksize:     Sobel aperture (3, 5, 7)
# k:         Harris free parameter (0.04 - 0.06)
dst = cv2.cornerHarris(gray, 2, 3, 0.04)

# dilate to mark corners
dst = cv2.dilate(dst, None)

# threshold and mark in red
img[dst > 0.01 * dst.max()] = [0, 0, 255]

Shi-Tomasi (goodFeaturesToTrack)

Shi-Tomasi améliore Harris en utilisant min(valeur_propre1, valeur_propre2) comme score, donnant des coins plus stables pour le suivi. maxCorners plafonne le nombre ; qualityLevel est une fraction de la plus forte réponse de coin (0.01 = 1 % du meilleur) ; minDistance impose une séparation spatiale entre coins détectés. C'est l'entrée par défaut du tracker de flux optique Lucas-Kanade.

opencv
import cv2
import numpy as np

img = cv2.imread("photo.jpg")
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)

# goodFeaturesToTrack returns the N strongest corners
corners = cv2.goodFeaturesToTrack(gray, maxCorners=100,
                                  qualityLevel=0.01,
                                  minDistance=10)
corners = np.int0(corners)

for c in corners:
    x, y = c.ravel()
    cv2.circle(img, (x, y), 3, (0, 0, 255), -1)

SIFT (caractéristiques invariantes à l'échelle)

SIFT trouve des points clés invariants à l'échelle et à la rotation avec un descripteur 128-D chacun — robuste à l'éclairage, au point de vue et à l'occlusion partielle. Breveté pendant des années, il est devenu libre dans OpenCV 4.4. Utilisez SIFT pour le matching haute précision quand la vitesse est secondaire. DRAW_RICH_KEYPOINTS dessine l'échelle et l'orientation de chaque point clé.

opencv
import cv2

img = cv2.imread("photo.jpg", cv2.IMREAD_GRAYSCALE)

# SIFT was patented; free since OpenCV 4.4 (contrib not required)
sift = cv2.SIFT_create()

# detect keypoints
kp = sift.detect(img, None)

# detect and compute descriptors
kp, des = sift.detectAndCompute(img, None)
print(len(kp), des.shape)   # N, (N, 128)

# draw keypoints
out = cv2.drawKeypoints(img, kp, None,
                        flags=cv2.DRAW_MATCHES_FLAGS_DRAW_RICH_KEYPOINTS)

ORB (FAST + BRIEF)

ORB combine le détecteur de points clés FAST au descripteur BRIEF — tous deux sans brevet et ~10x plus rapides que SIFT, faisant d'ORB le choix standard du matching temps réel sur mobile/embarqué. Les descripteurs sont binaires (32 octets vs 128 flottants de SIFT), donc le matching utilise la distance de Hamming. Légèrement moins robuste que SIFT à l'échelle/rotation, mais excellent pour le coût.

opencv
import cv2

img = cv2.imread("photo.jpg", cv2.IMREAD_GRAYSCALE)

# ORB: free, fast alternative to SIFT
orb = cv2.ORB_create(nfeatures=1000)

kp, des = orb.detectAndCompute(img, None)
print(len(kp), des.shape)   # N, (N, 32) — binary descriptors

# draw keypoints
out = cv2.drawKeypoints(img, kp, None, color=(0, 255, 0),
                        flags=0)

# FAST alone (detector only, no descriptor)
fast = cv2.FastFeatureDetector_create(threshold=20)
kp = fast.detect(img, None)

Détecteur FAST

FAST teste si un cercle de 16 pixels autour d'un candidat a N pixels contigus tous plus clairs ou tous plus sombres que le centre — extrêmement rapide grâce au court-circuit. Il ne retourne que des points clés, sans descripteurs (utilisez BRIEF ou ORB pour les descripteurs). Un seuil plus bas = plus de coins (et plus bruités) ; la suppression des non-maxima retire les doublons aux maxima locaux.

opencv
import cv2

img = cv2.imread("photo.jpg", cv2.IMREAD_GRAYSCALE)

# FAST: speed-optimized corner detector (detector only)
fast = cv2.FastFeatureDetector_create(threshold=20,
                                      nonmaxSuppression=True)

kp = fast.detect(img, None)
print(f"{len(kp)} keypoints")

# tune the threshold
fast.setThreshold(30)
print(f"threshold is now {fast.getThreshold()}")

# turn off non-max suppression to get more (clustered) corners
fast.setNonmaxSuppression(False)
kp_all = fast.detect(img, None)

MSER (régions extrémales stables)

MSER trouve les régions qui restent stables sur une plage de seuils d'intensité — idéal pour la détection de texte (où les lettres sont blobiformes), les plaques d'immatriculation et le texte de scène. Il gère bien l'éclairage inégal car chaque région est détectée à son propre seuil. Filtrez les résultats par ratio d'aspect et taille pour retirer le non-texte évident.

opencv
import cv2

img = cv2.imread("text.jpg", cv2.IMREAD_GRAYSCALE)

# MSER: detects stable connected regions across thresholds
mser = cv2.MSER_create()
regions, _ = mser.detectRegions(img)

# regions is a list of point arrays
out = cv2.cvtColor(img, cv2.COLOR_GRAY2BGR)
for pts in regions:
    x, y, w, h = cv2.boundingRect(pts)
    if 5 < h < 50:    # filter by likely text size
        cv2.rectangle(out, (x, y), (x+w, y+h), (0, 255, 0), 1)
14

Appariement de caractéristiques

Appariement force brute

L'appariement en force brute essaie chaque paire de descripteurs — exact mais O(N*M). Pour les descripteurs binaires d'ORB, utilisez NORM_HAMMING ; pour les descripteurs flottants SIFT/SURF, NORM_L2. crossCheck=True ne garde que les meilleurs matchs mutuels (le meilleur de A est B et inversement), retirant beaucoup de faux positifs. Chaque match a un .distance — plus petit est mieux.

opencv
import cv2

img1 = cv2.imread("box.png", cv2.IMREAD_GRAYSCALE)
img2 = cv2.imread("scene.png", cv2.IMREAD_GRAYSCALE)

orb = cv2.ORB_create()
kp1, des1 = orb.detectAndCompute(img1, None)
kp2, des2 = orb.detectAndCompute(img2, None)

# for ORB (binary descriptors) use Hamming distance
bf = cv2.BFMatcher(cv2.NORM_HAMMING, crossCheck=True)
matches = bf.match(des1, des2)

# sort by distance (best first)
matches = sorted(matches, key=lambda m: m.distance)

# draw top 20
out = cv2.drawMatches(img1, kp1, img2, kp2, matches[:20], None,
                      flags=cv2.DrawMatchesFlags_NOT_DRAW_SINGLE_POINTS)

Appariement FLANN

FLANN (Fast Library for Approximate Nearest Neighbors) construit un KD-tree (pour SIFT/SURF) ou LSH (pour ORB) pour trouver des matchs approximatifs — bien plus rapide que la force brute sur de grands ensembles de descripteurs, au prix de ratés occasionnels. Les paramètres trees et checks échangent précision contre vitesse. Utilisez FLANN avec des milliers de caractéristiques ; la force brute suffit pour de petits ensembles.

opencv
import cv2
import numpy as np

img1 = cv2.imread("box.png", cv2.IMREAD_GRAYSCALE)
img2 = cv2.imread("scene.png", cv2.IMREAD_GRAYSCALE)

sift = cv2.SIFT_create()
kp1, des1 = sift.detectAndCompute(img1, None)
kp2, des2 = sift.detectAndCompute(img2, None)

# FLANN parameters for SIFT (float descriptors)
FLANN_INDEX_KDTREE = 1
index_params = dict(algorithm=FLANN_INDEX_KDTREE, trees=5)
search_params = dict(checks=50)
flann = cv2.FlannBasedMatcher(index_params, search_params)

matches = flann.knnMatch(des1, des2, k=2)

Matching KNN et test de ratio

Le test de ratio de Lowe est le filtre standard de l'appariement de caractéristiques : gardez un match seulement si le meilleur est significativement plus proche que le deuxième (seuil typique 0.7-0.8). L'intuition : si les deux candidats sont aussi proches l'un que l'autre, le match est ambigu et probablement faux. Ce seul test retire la vaste majorité des faux positifs.

opencv
import cv2

img1 = cv2.imread("box.png", cv2.IMREAD_GRAYSCALE)
img2 = cv2.imread("scene.png", cv2.IMREAD_GRAYSCALE)

sift = cv2.SIFT_create()
kp1, des1 = sift.detectAndCompute(img1, None)
kp2, des2 = sift.detectAndCompute(img2, None)

bf = cv2.BFMatcher(cv2.NORM_L2)
matches = bf.knnMatch(des1, des2, k=2)   # 2 nearest neighbors

# Lowe's ratio test: keep only unambiguous matches
good = []
for m, n in matches:
    if m.distance < 0.75 * n.distance:
        good.append(m)

out = cv2.drawMatches(img1, kp1, img2, kp2, good, None,
                      flags=cv2.DrawMatchesFlags_NOT_DRAW_SINGLE_POINTS)

Homographie (RANSAC)

findHomography avec RANSAC calcule la transformation perspective qui mappe src vers dst en ignorant les aberrants — le masque d'inliers dit quels matchs s'accordent avec le modèle. Le seuil de reprojection (5.0) est en pixels ; plus bas = plus strict. Il faut au moins 4 bons matchs. Utilisez cela pour localiser un objet connu dans une scène ou aligner des photos qui se chevauchent.

opencv
import cv2
import numpy as np

img1 = cv2.imread("box.png", cv2.IMREAD_GRAYSCALE)
img2 = cv2.imread("scene.png", cv2.IMREAD_GRAYSCALE)

sift = cv2.SIFT_create()
kp1, des1 = sift.detectAndCompute(img1, None)
kp2, des2 = sift.detectAndCompute(img2, None)

bf = cv2.BFMatcher(cv2.NORM_L2)
matches = bf.knnMatch(des1, des2, k=2)
good = [m for m, n in matches if m.distance < 0.75 * n.distance]

# build point correspondences
src = np.float32([kp1[m.queryIdx].pt for m in good]).reshape(-1, 1, 2)
dst = np.float32([kp2[m.trainIdx].pt for m in good]).reshape(-1, 1, 2)

# RANSAC homography
H, mask = cv2.findHomography(src, dst, cv2.RANSAC, 5.0)
inliers = mask.ravel().tolist()
print(f"{sum(inliers)} inliers / {len(good)} matches")

Localisation d'objet

Voici le pipeline classique de localisation d'objet : détecter les caractéristiques dans les deux images, les apparier, ajuster une homographie avec RANSAC, puis projeter la boîte englobante de l'objet dans la scène. Marche pour des objets plans ou des objets 3D lointains (où la perspective domine). Échoue sur les objets sans texture, symétriques ou fortement occlus — pour ceux-là, utilisez des détecteurs de deep learning.

opencv
import cv2
import numpy as np

img1 = cv2.imread("box.png", cv2.IMREAD_GRAYSCALE)
img2 = cv2.imread("scene.png", cv2.IMREAD_GRAYSCALE)

sift = cv2.SIFT_create()
kp1, des1 = sift.detectAndCompute(img1, None)
kp2, des2 = sift.detectAndCompute(img2, None)

bf = cv2.BFMatcher(cv2.NORM_L2)
good = [m for m, n in bf.knnMatch(des1, des2, k=2)
        if m.distance < 0.75 * n.distance]

src = np.float32([kp1[m.queryIdx].pt for m in good]).reshape(-1, 1, 2)
dst = np.float32([kp2[m.trainIdx].pt for m in good]).reshape(-1, 1, 2)

H, _ = cv2.findHomography(src, dst, cv2.RANSAC, 5.0)

# project the object's corners into the scene
h, w = img1.shape
corners = np.float32([[0, 0], [w-1, 0], [w-1, h-1], [0, h-1]]).reshape(-1, 1, 2)
scene_corners = cv2.perspectiveTransform(corners, H)

out = cv2.cvtColor(img2, cv2.COLOR_GRAY2BGR)
cv2.polylines(out, [np.int32(scene_corners)], True, (0, 255, 0), 3)
15

Détection de visages

Classifieur en cascade de Haar

Les cascades de Haar sont le détecteur classique Viola-Jones — rapide sur CPU et bon pour les visages de face, mais moins précis que les détecteurs modernes de deep learning (MTCNN, SSD, RetinaFace). scaleFactor (>1) contrôle la recherche multi-échelle — 1.1 = pas d'échelle de 10 % ; plus petit = plus lent mais plus complet. minNeighbors filtre les détections qui se chevauchent ; augmentez-le pour réduire les faux positifs.

opencv
import cv2

# load a pretrained cascade (shipped with OpenCV)
cascade_path = cv2.data.haarcascades + "haarcascade_frontalface_default.xml"
face_cascade = cv2.CascadeClassifier(cascade_path)

print(face_cascade.empty())   # False = loaded ok

img = cv2.imread("people.jpg")
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)

# detectMultiScale(gray, scaleFactor, minNeighbors, minSize, maxSize)
faces = face_cascade.detectMultiScale(
    gray, scaleFactor=1.1, minNeighbors=5, minSize=(30, 30))

for (x, y, w, h) in faces:
    cv2.rectangle(img, (x, y), (x+w, y+h), (255, 0, 0), 2)

Détecter des visages dans une image

Détecter les yeux (ou le sourire) dans la ROI du visage est l'astuce d'efficacité standard : chercher les yeux dans toute l'image donne beaucoup de faux positifs, mais dans une ROI de visage confirmée ils sont rares. cv2.data.haarcascades pointe vers le répertoire XML fourni — d'autres cascades (yeux, sourire, corps entier, plaque) sont disponibles. Rognage de la ROI AVANT d'appeler la cascade.

opencv
import cv2

face_cascade = cv2.CascadeClassifier(
    cv2.data.haarcascades + "haarcascade_frontalface_default.xml")
eye_cascade = cv2.CascadeClassifier(
    cv2.data.haarcascades + "haarcascade_eye.xml")

img = cv2.imread("people.jpg")
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)

faces = face_cascade.detectMultiScale(gray, 1.3, 5)
for (fx, fy, fw, fh) in faces:
    cv2.rectangle(img, (fx, fy), (fx+fw, fy+fh), (255, 0, 0), 2)

    # search for eyes INSIDE the face region (faster, fewer false positives)
    roi_gray = gray[fy:fy+fh, fx:fx+fw]
    roi_color = img[fy:fy+fh, fx:fx+fw]
    eyes = eye_cascade.detectMultiScale(roi_gray)
    for (ex, ey, ew, eh) in eyes:
        cv2.rectangle(roi_color, (ex, ey), (ex+ew, ey+eh), (0, 255, 0), 2)

Détecter des visages dans une vidéo

La détection de visages temps réel sur webcam est faisable sur CPU grâce à la vitesse des cascades de Haar. L'astuce de flou de ROI (GaussianBlur sur la seule région du visage) est une simple technique de confidentialité/anonymisation. Pour suivre les visages entre trames (éviter le scintillement), associez les détections par IoU et lissez avec un filtre de Kalman — les cascades seules n'ont aucune continuité temporelle.

opencv
import cv2

face_cascade = cv2.CascadeClassifier(
    cv2.data.haarcascades + "haarcascade_frontalface_default.xml")

cap = cv2.VideoCapture(0)
while True:
    ret, frame = cap.read()
    if not ret:
        break

    gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)
    faces = face_cascade.detectMultiScale(gray, 1.1, 5)

    for (x, y, w, h) in faces:
        cv2.rectangle(frame, (x, y), (x+w, y+h), (0, 255, 0), 2)
        # blur the face for privacy
        frame[y:y+h, x:x+w] = cv2.GaussianBlur(
            frame[y:y+h, x:x+w], (25, 25), 30)

    cv2.imshow("face", frame)
    if cv2.waitKey(1) & 0xFF == ord('q'):
        break

cap.release()
cv2.destroyAllWindows()

Visage de profil / de côté

Les cascades de Haar sont spécifiques à la pose — la cascade frontale rate les visages de côté, donc combinez-la avec la cascade de profil. Comme la cascade de profil est entraînée sur un côté, détectez l'autre en retournant l'image horizontalement et en reflétant les coordonnées obtenues. Cela rate quand même les vues 3/4 ; les détecteurs modernes (DNN, MTCNN) gèrent toutes les poses en un modèle.

opencv
import cv2

profile_cascade = cv2.CascadeClassifier(
    cv2.data.haarcascades + "haarcascade_profileface.xml")

img = cv2.imread("people.jpg")
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)

# detect left-facing profiles
profiles = profile_cascade.detectMultiScale(gray, 1.1, 5)
for (x, y, w, h) in profiles:
    cv2.rectangle(img, (x, y), (x+w, y+h), (0, 0, 255), 2)

# also detect right-facing by flipping the image
flipped = cv2.flip(gray, 1)
profiles_r = profile_cascade.detectMultiScale(flipped, 1.1, 5)
h, w = gray.shape
for (x, y, fw, fh) in profiles_r:
    cv2.rectangle(img, (w - x - fw, y), (w - x, y + fh), (255, 0, 0), 2)

Détection de visages par DNN

Le module dnn d'OpenCV peut exécuter des modèles préentraînés Caffe/TensorFlow/ONNX — les détecteurs de visages SSD et ResNet sont bien plus précis que les cascades de Haar et gèrent toutes les poses en un modèle. blobFromImage fait soustraction de moyenne et mise à l'échelle d'un coup. Les détections sont normalisées [0,1] — multipliez par (w, h, w, h) pour des boîtes en pixels. Modèles : SSD (Caffe), YuNet (ONNX, via cv.FaceDetectorYN).

opencv
import cv2
import numpy as np

model = cv2.dnn.readNetFromCaffe(
    "deploy.prototxt", "weights.caffemodel")

img = cv2.imread("people.jpg")
h, w = img.shape[:2]

# build a 300x300 blob (mean subtraction + scale)
blob = cv2.dnn.blobFromImage(img, 1.0, (300, 300), (104, 177, 123))

model.setInput(blob)
detections = model.forward()   # shape (1, 1, N, 7)

for i in range(detections.shape[2]):
    conf = detections[0, 0, i, 2]
    if conf > 0.5:
        box = detections[0, 0, i, 3:7] * np.array([w, h, w, h])
        x1, y1, x2, y2 = box.astype(int)
        cv2.rectangle(img, (x1, y1), (x2, y2), (0, 255, 0), 2)
        cv2.putText(img, f"{conf:.2f}", (x1, y1 - 5),
                    cv2.FONT_HERSHEY_SIMPLEX, 0.5, (0, 255, 0), 1)
16

Détection d'objets

Descripteur HOG

HOG (Histogram of Oriented Gradients) décrit la forme locale via des histogrammes de directions de contours — combiné à un SVM linéaire, c'est un détecteur d'objets classique. Le détecteur de personnes préentraîné marche pour les piétons entiers debout. winStride et scale échangent vitesse contre rappel. Les détecteurs profonds modernes (YOLO, SSD) sont bien plus précis mais HOG tourne sur CPU sans fichier de modèle.

opencv
import cv2

img = cv2.imread("person.jpg", cv2.IMREAD_GRAYSCALE)

# create HOG descriptor with the default detector
hog = cv2.HOGDescriptor()
hog.setSVMDetector(cv2.HOGDescriptor_getDefaultPeopleDetector())

# detectMultiScale returns (rectangles, weights)
boxes, weights = hog.detectMultiScale(
    img, winStride=(8, 8), padding=(4, 4), scale=1.05)

for (x, y, w, h) in boxes:
    cv2.rectangle(img, (x, y), (x+w, y+h), (0, 255, 0), 2)

Visualisation des caractéristiques HOG

La fenêtre HOG standard est 64x128 pixels (la taille piéton INRIA). Paramètres : fenêtre (64x128), bloc (16x16), pas de bloc (8x8), cellule (8x8), bins (9). Chaque descripteur fait 3780-D. Pour classer des objets personnalisés, extrayez les caractéristiques HOG de nombreux échantillons positifs/négatifs et entraînez un SVM linéaire (scikit-learn), puis réglez le détecteur avec setSVMDetector.

opencv
import cv2

img = cv2.imread("person.jpg", cv2.IMREAD_GRAYSCALE)
img = cv2.resize(img, (64, 128))   # standard HOG window

hog = cv2.HOGDescriptor((64, 128), (16, 16), (8, 8), (8, 8), 9)
descriptor = hog.compute(img)
print(descriptor.shape)   # (3780, 1)

# 9 bins per cell, 7x15 cells, 4 cells per block -> 3780 features
# this is the input vector to a linear SVM classifier

Appariement de gabarits

L'appariement de gabarits glisse le gabarit sur l'image et calcule un score de similarité — ne marche que pour des correspondances exactes (ou quasi) sans rotation ni changement d'échelle. TM_CCOEFF_NORMED est la méthode la plus robuste ; les résultats vont de [-1, 1]. Pour des matchs multiples, seuillez la carte de réponse et appliquez la suppression des non-maxima pour éviter les détections superposées.

opencv
import cv2
import numpy as np

img = cv2.imread("scene.png", cv2.IMREAD_GRAYSCALE)
template = cv2.imread("template.png", cv2.IMREAD_GRAYSCALE)
h, w = template.shape

# matchTemplate returns a correlation map
res = cv2.matchTemplate(img, template, cv2.TM_CCOEFF_NORMED)

# find the best match
min_val, max_val, min_loc, max_loc = cv2.minMaxLoc(res)
top_left = max_loc
bottom_right = (top_left[0] + w, top_left[1] + h)

out = cv2.cvtColor(img, cv2.COLOR_GRAY2BGR)
cv2.rectangle(out, top_left, bottom_right, (0, 255, 0), 2)

# find all matches above a threshold
loc = np.where(res >= 0.8)
for pt in zip(*loc[::-1]):
    cv2.rectangle(out, pt, (pt[0] + w, pt[1] + h), (0, 0, 255), 1)

Appariement de gabarits multi-échelle

L'appariement multi-échelle brute-force une plage d'échelles — lent mais marche quand la taille du gabarit dans l'image est inconnue. Il ne gère toujours pas la rotation ; pour cela il faudrait aussi balayer les angles (très lent) ou utiliser l'appariement de caractéristiques. Pour la détection d'objets en production, utilisez un détecteur entraîné (YOLO, SSD) plutôt que l'appariement de gabarits.

opencv
import cv2
import numpy as np

img = cv2.imread("scene.png", cv2.IMREAD_GRAYSCALE)
template = cv2.imread("template.png", cv2.IMREAD_GRAYSCALE)

best = (-1, None, None)   # (score, location, scale)
for scale in np.linspace(0.5, 1.5, 20):
    resized = cv2.resize(template, None, fx=scale, fy=scale)
    rh, rw = resized.shape
    if rh > img.shape[0] or rw > img.shape[1]:
        continue
    res = cv2.matchTemplate(img, resized, cv2.TM_CCOEFF_NORMED)
    _, max_val, _, max_loc = cv2.minMaxLoc(res)
    if max_val > best[0]:
        best = (max_val, max_loc, scale)

score, (x, y), scale = best
h, w = template.shape
out = cv2.cvtColor(img, cv2.COLOR_GRAY2BGR)
rw, rh = int(w * scale), int(h * scale)
cv2.rectangle(out, (x, y), (x + rw, y + rh), (0, 255, 0), 2)

Détection d'objets par DNN (YOLO)

Le module dnn d'OpenCV peut exécuter des poids exportés YOLO/SSD/Faster-RCNN — utile quand on ne peut pas installer un framework DL complet. Le parsing des sorties YOLO est verbeux : chaque détection a un centre, une taille, un objectness et des scores par classe. Appliquez toujours NMSBoxes (suppression des non-maxima) pour replier les boîtes superposées en une. Pour le temps réel, YOLOv4-tiny ou basculez vers ONNX + un backend plus rapide.

opencv
import cv2
import numpy as np

# load a YOLO model (weights + cfg)
net = cv2.dnn.readNet("yolov3.weights", "yolov3.cfg")
with open("coco.names") as f:
    classes = [line.strip() for line in f.readlines()]

layer_names = net.getLayerNames()
out_layers = [layer_names[i - 1] for i in net.getUnconnectedOutLayers()]

img = cv2.imread("street.jpg")
blob = cv2.dnn.blobFromImage(img, 1/255.0, (416, 416), swapRB=True, crop=False)
net.setInput(blob)
outputs = net.forward(out_layers)

# parse YOLO output: each detection is [cx, cy, w, h, obj, class_scores...]
h, w = img.shape[:2]
boxes, confs, ids = [], [], []
for out in outputs:
    for det in out:
        scores = det[5:]
        cls = int(np.argmax(scores))
        conf = scores[cls]
        if conf > 0.5:
            cx, cy, bw, bh = (det[:4] * [w, h, w, h]).astype(int)
            boxes.append([cx - bw//2, cy - bh//2, bw, bh])
            confs.append(float(conf))
            ids.append(cls)

idxs = cv2.dnn.NMSBoxes(boxes, confs, 0.5, 0.4)   # non-max suppression
17

Segmentation d'images

Clustering K-Means

K-means clusterise les pixels par couleur — un moyen simple de postériser ou segmenter une image en K couleurs dominantes. Passez les pixels en float32 sous forme (N, 3) (ou (N, 5) si vous ajoutez les coordonnées xy pour un clustering spatial). Augmenter K donne une séparation de couleurs plus fine. Pour une cohérence spatiale, augmentez chaque pixel de ses coordonnées (x, y) ; pour une quantification pure de couleurs, gardez seulement BGR.

opencv
import cv2
import numpy as np

img = cv2.imread("photo.jpg")
h, w = img.shape[:2]

# reshape to a list of pixels (N, 3) in float32
pixels = img.reshape(-1, 3).astype(np.float32)

# kmeans(data, K, criteria, attempts, flags)
K = 4
criteria = (cv2.TERM_CRITERIA_EPS + cv2.TERM_CRITERIA_MAX_ITER, 20, 1.0)
_, labels, centers = cv2.kmeans(pixels, K, None, criteria, 10,
                                cv2.KMEANS_RANDOM_CENTERS)

# rebuild the image with cluster centers
centers = np.uint8(centers)
seg = centers[labels.flatten()].reshape((h, w, 3))

GrabCut

GrabCut est un extracteur de premier plan interactif — vous donnez un rectangle englobant et il modélise itérativement premier plan/fond avec des mélanges de gaussiennes. Pour des résultats plus fins, raffinez avec GC_INIT_WITH_MASK après étiquetage manuel de pixels (fg certain / bg certain). Marche bien pour un objet saillant unique sur un fond relativement simple.

opencv
import cv2
import numpy as np

img = cv2.imread("person.jpg")
h, w = img.shape[:2]

# initialize mask (all probable background)
mask = np.zeros((h, w), np.uint8)

# define a rectangle around the foreground object
rect = (50, 50, w - 100, h - 100)

# internal scratch arrays
bgd = np.zeros((1, 65), np.float64)
fgd = np.zeros((1, 65), np.float64)

# run GrabCut: 5 iterations
cv2.grabCut(img, mask, rect, bgd, fgd, 5, cv2.GC_INIT_WITH_RECT)

# mask values: 0=bg, 1=fg, 2=probable bg, 3=probable fg
fg_mask = np.where((mask == 1) | (mask == 3), 255, 0).astype(np.uint8)
result = cv2.bitwise_and(img, img, mask=fg_mask)

Watershed

Watershed traite l'image comme une carte topographique (intensité = altitude) et « inonde » les bassins depuis des marqueurs de graines — sans bonnes graines, il produit une sévère sur-segmentation. L'astuce de la transformée de distance génère des graines de premier plan sûres pour des objets qui se touchent (ex. pièces superposées). Marqueurs : 0=inconnu, 1=fond, 2..N=objets, -1=frontière. C'est le pipeline classique « séparer les objets qui se touchent ».

opencv
import cv2
import numpy as np

img = cv2.imread("coins.jpg")
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)

# threshold to separate coins from background
_, binary = cv2.threshold(gray, 0, 255,
                          cv2.THRESH_BINARY_INV + cv2.THRESH_OTSU)

# noise removal
kernel = np.ones((3, 3), np.uint8)
opening = cv2.morphologyEx(binary, cv2.MORPH_OPEN, kernel, iterations=2)

# sure background area
sure_bg = cv2.dilate(opening, kernel, iterations=3)

# sure foreground: distance transform + threshold
dist = cv2.distanceTransform(opening, cv2.DIST_L2, 5)
_, sure_fg = cv2.threshold(dist, 0.5 * dist.max(), 255, 0)
sure_fg = np.uint8(sure_fg)

# unknown region (between sure fg and sure bg)
unknown = cv2.subtract(sure_bg, sure_fg)

# marker labelling
_, markers = cv2.connectedComponents(sure_fg)
markers = markers + 1
markers[unknown == 255] = 0

# watershed modifies markers in place
markers = cv2.watershed(img, markers)
img[markers == -1] = [255, 0, 0]   # boundaries in red

Flood Fill

floodFill est l'outil baguette magique — partez d'un pixel graine et remplissez tous les pixels connectés dont la couleur est dans loDiff/upDiff de la graine (FIXED_RANGE) ou du pixel précédent. Le masque doit dépasser l'image de 2 pixels (une bordure d'un pixel de chaque côté). Utile pour la croissance de région, le remplacement simple de fond et la sélection interactive.

opencv
import cv2

img = cv2.imread("photo.jpg")
h, w = img.shape[:2]
mask = np.zeros((h + 2, w + 2), np.uint8)

# floodFill fills a connected region similar to the seed pixel
# (image, mask, seedPoint, newVal, loDiff, upDiff, flags)
cv2.floodFill(img, mask, (100, 100), (0, 255, 0),
              loDiff=(20, 20, 20), upDiff=(20, 20, 20),
              flags=8 | cv2.FLOODFILL_FIXED_RANGE)

# FLOODFILL_FIXED_RANGE: compare to the seed pixel (strict)
# 4-connectivity (4) or 8-connectivity (8)

# extract the filled mask
filled_mask = mask[1:-1, 1:-1]   # the mask is padded by 1

Composantes connexes

connectedComponents étiquette chaque région blanche d'un entier unique — plus rapide que findContours quand vous n'avez besoin que du compte, de l'aire et des centroïdes. connectedComponentsWithStats retourne aussi boîtes englobantes et aires. Le label 0 est toujours le fond. La connectivité par défaut est 8 (diagonales incluses) ; passez connectivity=4 pour plus strict. Utilisez cela pour le comptage de particules et l'analyse de blobs.

opencv
import cv2
import numpy as np

img = cv2.imread("blobs.png", cv2.IMREAD_GRAYSCALE)
_, binary = cv2.threshold(img, 127, 255, cv2.THRESH_BINARY)

# connectedComponents returns (num_labels, labels)
num, labels = cv2.connectedComponents(binary)
print(f"found {num - 1} objects (label 0 is background)")

# connectedComponentsWithStats also gives area and bounding box
num, labels, stats, centroids = cv2.connectedComponentsWithStats(binary)
for i in range(1, num):
    x, y, w, h, area = stats[i]
    cx, cy = centroids[i]
    cv2.rectangle(img, (x, y), (x+w, y+h), (0, 255, 0), 1)
    cv2.putText(img, str(area), (x, y - 5),
                cv2.FONT_HERSHEY_SIMPLEX, 0.4, (0, 0, 255), 1)

Mean-Shift / PyrMeanShiftFiltering

pyrMeanShiftFiltering est une segmentation non paramétrique qui « aplatit » les régions de couleur similaire en préservant les contours — souvent en prétraitement avant une segmentation par contours. sp (rayon spatial) contrôle jusqu'où l'algorithme regarde spatialement ; sr (rayon de couleur) la tolérance de couleur. Des valeurs plus grandes produisent des régions plus grandes et plus lisses.

opencv
import cv2

img = cv2.imread("photo.jpg")

# pyrMeanShiftFiltering: edge-preserving smoothing that homogenizes regions
# (spatialRadius, colorRadius) — larger values merge more
filtered = cv2.pyrMeanShiftFiltering(img, sp=20, sr=40)

# now segment on the filtered image
gray = cv2.cvtColor(filtered, cv2.COLOR_BGR2GRAY)
_, binary = cv2.threshold(gray, 0, 255,
                          cv2.THRESH_BINARY + cv2.THRESH_OTSU)

contours, _ = cv2.findContours(binary, cv2.RETR_EXTERNAL,
                               cv2.CHAIN_APPROX_SIMPLE)
out = img.copy()
cv2.drawContours(out, contours, -1, (0, 255, 0), 2)
18

Calibration de caméra

Calibration par damier

La calibration de caméra trouve la matrice intrinsèque (focale, point principal) et les coefficients de distorsion de l'objectif depuis des images d'un motif connu (le damier est standard car les coins se détectent facilement). Il faut ~10-20 images sous des angles variés. cornerSubPix raffine les coins à la précision sous-pixel — essentiel pour une bonne calibration. La taille du motif passée à findChessboardCorners est en coins intérieurs (cases-1).

opencv
import cv2
import numpy as np
import glob

# prepare object points (0,0,0), (1,0,0), ..., for a 7x6 board
objp = np.zeros((6 * 7, 3), np.float32)
objp[:, :2] = np.mgrid[0:7, 0:6].T.reshape(-1, 2)

objpoints = []   # 3-D real-world points
imgpoints = []   # 2-D image points

for fname in glob.glob("calib/*.jpg"):
    img = cv2.imread(fname)
    gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)

    # findChessboardCorners returns corners (or None)
    ret, corners = cv2.findChessboardCorners(gray, (7, 6), None)
    if ret:
        # refine to sub-pixel accuracy
        corners2 = cv2.cornerSubPix(gray, corners, (11, 11), (-1, -1),
            (cv2.TERM_CRITERIA_EPS + cv2.TERM_CRITERIA_MAX_ITER, 30, 0.001))
        objpoints.append(objp)
        imgpoints.append(corners2)

# calibrate
ret, mtx, dist, rvecs, tvecs = cv2.calibrateCamera(
    objpoints, imgpoints, gray.shape[::-1], None, None)
print("camera matrix:\n", mtx)

Corriger la distorsion (undistort)

undistort retire la distorsion radiale et tangentielle de l'objectif avec les paramètres de calibration. Pour la vidéo, précalculez les maps une fois avec initUndistortRectifyMap et appliquez remap à chaque trame — bien plus rapide que d'appeler undistort répétitivement. getOptimalNewCameraMatrix avec alpha=1 garde tous les pixels (avec bordures noires) ; alpha=0 rogne à la région valide.

opencv
import cv2
import numpy as np

# mtx, dist come from calibrateCamera
img = cv2.imread("distorted.jpg")
h, w = img.shape[:2]

# method 1: simple undistort
undistorted = cv2.undistort(img, mtx, dist)

# method 2: pre-compute the maps for speed (run once, reuse many times)
newcameramtx, roi = cv2.getOptimalNewCameraMatrix(
    mtx, dist, (w, h), 1, (w, h))
mapx, mapy = cv2.initUndistortRectifyMap(
    mtx, dist, None, newcameramtx, (w, h), cv2.CV_16SC2)
undistorted2 = cv2.remap(img, mapx, mapy, cv2.INTER_LINEAR)

# crop to the valid ROI
x, y, rw, rh = roi
undistorted2 = undistorted2[y:y+rh, x:x+rw]

Estimation de pose (ArUco)

Les marqueurs ArUco sont des marqueurs carrés fiduciaires (comme des QR codes) pour l'estimation de pose — connaissant la taille physique du marqueur et la calibration de la caméra, on obtient sa rotation 3-D (rvec) et sa translation (tvec) relatives à la caméra. Disponible dans opencv-contrib. drawFrameAxes dessine les axes locaux X/Y/Z du marqueur — rouge=X, vert=Y, bleu=Z, longueur en mètres.

opencv
import cv2

# load a predefined ArUco dictionary
aruco_dict = cv2.aruco.getPredefinedDictionary(cv2.aruco.DICT_4X4_50)
params = cv2.aruco.DetectorParameters()
detector = cv2.aruco.ArucoDetector(aruco_dict, params)

img = cv2.imread("marker.png")
corners, ids, rejected = detector.detectMarkers(img)

if ids is not None:
    cv2.aruco.drawDetectedMarkers(img, corners, ids)

    # estimate pose (marker size in meters, camera matrix, distortion)
    rvecs, tvecs, _ = cv2.aruco.estimatePoseSingleMarkers(
        corners, 0.05, mtx, dist)
    for rvec, tvec in zip(rvecs, tvecs):
        cv2.drawFrameAxes(img, mtx, dist, rvec, tvec, 0.05)

Pose fiduciaire (SolvePnP)

solvePnP (Perspective-n-Point) récupère la pose de la caméra depuis N correspondances 3-D vers 2-D — au moins 4 points. Utilisez SOLVEPNP_ITERATIVE (défaut) pour la précision ou SOLVEPNP_IPPE pour des cibles planes. Le rvec est un vecteur de rotation (axe × angle) ; utilisez Rodrigues pour convertir en matrice 3x3. C'est le socle de la RA par marqueurs et du suivi 6-DDL.

opencv
import cv2
import numpy as np

# 3-D coordinates of known object points (e.g. a cube corner)
obj_points = np.array([
    [0, 0,  0], [1, 0,  0], [1, 1,  0], [0, 1,  0],
    [0, 0, -1], [1, 0, -1], [1, 1, -1], [0, 1, -1],
], dtype=np.float32)

# corresponding 2-D image points (detected via feature matching etc.)
img_points = np.array([
    [120, 90], [220, 88], [225, 190], [115, 195],
    [80, 60],  [240, 55], [248, 210], [70, 215],
], dtype=np.float32)

# solvePnP(objectPoints, imagePoints, cameraMatrix, distCoeffs)
ret, rvec, tvec = cv2.solvePnP(obj_points, img_points, mtx, dist)
print("rotation:", rvec.ravel())
print("translation:", tvec.ravel())

# project the 3-D points back to verify
proj, _ = cv2.projectPoints(obj_points, rvec, tvec, mtx, dist)

Erreur de reprojection

L'erreur de reprojection est l'étalon-or de la qualité de calibration — elle mesure à quelle distance les points 3-D projetés atterrissent des points 2-D détectés. Une bonne calibration est sous 0,5 px en moyenne ; au-dessus de 1 px signale généralement un mauvais jeu d'images, une mauvaise taille de motif ou du flou de mouvement. L'erreur par image aide à trouver et écarter les images de calibration mauvaises.

opencv
import cv2
import numpy as np

# after calibrateCamera or solvePnP, check accuracy
mean_err = 0
total = 0
for i in range(len(objpoints)):
    # project the 3-D points using the estimated pose
    proj, _ = cv2.projectPoints(objpoints[i], rvecs[i], tvecs[i], mtx, dist)
    err = cv2.norm(imgpoints[i], proj, cv2.NORM_L2) / len(proj)
    mean_err += err
    total += 1

print(f"mean reprojection error: {mean_err / total:.3f} px")
# good calibrations are typically < 0.5 px per corner
19

Profondeur et stéréo

Carte de disparité stéréo

StereoBM calcule une carte de disparité (décalage de pixels gauche/droite) pour une paire stéréo rectifiée — les objets proches ont une disparité plus grande. numDisparities doit être multiple de 16 ; blockSize impair. La sortie est en int16 multipliée par 16 (divisez par 16.0 pour la disparité en pixels). StereoSGBM (semi-global block matching) est plus lent mais bien plus précis.

opencv
import cv2

# stereo pair (rectified: corresponding points on the same row)
imgL = cv2.imread("left.png", cv2.IMREAD_GRAYSCALE)
imgR = cv2.imread("right.png", cv2.IMREAD_GRAYSCALE)

# StereoBM (block matching, fast)
stereo = cv2.StereoBM_create(numDisparities=16, blockSize=15)
disparity = stereo.compute(imgL, imgR)

# normalize for display
disp_vis = cv2.normalize(disparity, None, 0, 255,
                         cv2.NORM_MINMAX, cv2.CV_8U)

StereoSGBM

StereoSGBM impose de la douceur entre lignes de balayage (semi-global matching) — bien plus précis que StereoBM au prix d'un runtime ~5x. P1/P2 pénalisent respectivement les changements de disparité de 1 et >1 ; règle empirique : P1=8*C*blockSize² et P2=32*C*blockSize² où C est le nombre de canaux. Les paramètres speckle* filtrent les petites régions de disparité bruitées.

opencv
import cv2

imgL = cv2.imread("left.png", cv2.IMREAD_GRAYSCALE)
imgR = cv2.imread("right.png", cv2.IMREAD_GRAYSCALE)

sgbm = cv2.StereoSGBM_create(
    minDisparity=0,
    numDisparities=128,
    blockSize=5,
    P1=8 * 3 * 5 * 5,
    P2=32 * 3 * 5 * 5,
    disp12MaxDiff=1,
    uniquenessRatio=10,
    speckleWindowSize=100,
    speckleRange=32,
)

disparity = sgbm.compute(imgL, imgR)
disp_vis = cv2.normalize(disparity, None, 0, 255,
                         cv2.NORM_MINMAX, cv2.CV_8U)

Calibration et rectification stéréo

Le matching stéréo exige des images rectifiées — lignes épipolaires alignées horizontalement pour que les points correspondants partagent une ligne. Le pipeline : calibrer chaque caméra, calibrer en stéréo pour trouver R et T entre elles, stereoRectify pour les transformations de rectification, puis remap chaque trame une fois. Après rectification, le calcul de disparité est une recherche 1-D le long des lignes.

opencv
import cv2
import numpy as np

# calibrate each camera separately, then stereo-calibrate
ret, mtxL, distL, rvecsL, tvecsL = cv2.calibrateCamera(
    objpoints, imgpointsL, grayL.shape[::-1], None, None)
ret, mtxR, distR, rvecsR, tvecsR = cv2.calibrateCamera(
    objpoints, imgpointsR, grayR.shape[::-1], None, None)

# stereo calibration: finds the rigid transform between cameras
flags = cv2.CALIB_FIX_INTRINSIC
ret, mtxL, distL, mtxR, distR, R, T, E, F = cv2.stereoCalibrate(
    objpoints, imgpointsL, imgpointsR, mtxL, distL, mtxR, distR,
    grayL.shape[::-1], flags=flags)

# stereo rectification: aligns epipolar lines to be horizontal
R1, R2, P1, P2, Q, _, _ = cv2.stereoRectify(
    mtxL, distL, mtxR, distR, grayL.shape[::-1], R, T)

# pre-compute the rectification maps
mapL1, mapL2 = cv2.initUndistortRectifyMap(
    mtxL, distL, R1, P1, grayL.shape[::-1], cv2.CV_16SC2)
mapR1, mapR2 = cv2.initUndistortRectifyMap(
    mtxR, distR, R2, P2, grayR.shape[::-1], cv2.CV_16SC2)

rectL = cv2.remap(imgL, mapL1, mapL2, cv2.INTER_LINEAR)
rectR = cv2.remap(imgR, mapR1, mapR2, cv2.INTER_LINEAR)

Profondeur depuis la disparité

La profondeur est inversement proportionnelle à la disparité : profondeur = focale × base / disparité. La base (séparation des caméras) et la focale doivent être en unités cohérentes (typiquement pixels pour la focale, mètres pour la base donne la profondeur en mètres). La disparité est bruitée pour les objets lointains (faible disparité, grande erreur de profondeur) — voilà pourquoi les caméras stéréo exigent une base large pour la longue portée.

opencv
import cv2
import numpy as np

# given a disparity map and the stereo baseline + focal length:
# depth = (focal_length * baseline) / disparity

focal = 700.0       # pixels (from camera matrix)
baseline = 0.1      # meters (distance between cameras)

disparity = sgbm.compute(rectL, rectR).astype(np.float32) / 16.0

# avoid division by zero
disparity[disparity <= 0] = 0.1
depth = (focal * baseline) / disparity   # in meters

# cap to a sensible range
depth = np.clip(depth, 0.1, 100.0)
depth_vis = cv2.normalize(depth, None, 0, 255, cv2.NORM_MINMAX, cv2.CV_8U)

Flux optique (Lucas-Kanade)

Lucas-Kanade calcule un flux optique épars — il suit un ensemble de points clés entre trames en supposant un petit mouvement local. Rapide et précis pour un mouvement modéré ; échoue pour un mouvement grand ou rapide (utilisez une pyramide, ce que calcOpticalFlowPyrLK fait déjà). status==1 signifie que le point a été suivi avec succès. Pour un flux dense pixel par pixel, calcOpticalFlowFarneback — bien plus lent mais produit un champ de mouvement complet.

opencv
import cv2
import numpy as np

cap = cv2.VideoCapture("traffic.mp4")
ret, prev = cap.read()
prev_gray = cv2.cvtColor(prev, cv2.COLOR_BGR2GRAY)

# detect good features to track
prev_pts = cv2.goodFeaturesToTrack(prev_gray, 100, 0.3, 7)

while True:
    ret, frame = cap.read()
    if not ret:
        break
    gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)

    # sparse optical flow (Lucas-Kanade)
    next_pts, status, err = cv2.calcOpticalFlowPyrLK(
        prev_gray, gray, prev_pts, None)

    good_new = next_pts[status == 1]
    good_old = prev_pts[status == 1]

    for new, old in zip(good_new, good_old):
        a, b = new.ravel()
        c, d = old.ravel()
        cv2.line(frame, (int(a), int(b)), (int(c), int(d)), (0, 255, 0), 2)
        cv2.circle(frame, (int(a), int(b)), 3, (0, 0, 255), -1)

    cv2.imshow("flow", frame)
    if cv2.waitKey(1) & 0xFF == ord('q'):
        break
    prev_gray = gray.copy()
    prev_pts = good_new.reshape(-1, 1, 2)

cap.release()
20

Utilitaires et astuces

Mesure de performance

TickMeter est la façon la plus propre de benchmarker les appels OpenCV — getTimeMilli retourne des millisecondes d'horloge. getTickCount/getTickFrequency donnent un timing précis au cycle. Moyenne toujours sur de nombreuses itérations pour amortir le jitter, et désactivez cv2.imshow en benchmark (le rendu GUI domine). setNumThreads contrôle le backend parallèle sous-jacent (TBB/OpenMP).

opencv
import cv2
import numpy as np

img = cv2.imread("photo.jpg")

# TickMeter: high-precision timer
tm = cv2.TickMeter()
tm.start()
for _ in range(100):
    blurred = cv2.GaussianBlur(img, (5, 5), 0)
tm.stop()
print(f"avg: {tm.getTimeMilli() / 100:.3f} ms")

# getTickCount / getTickFrequency
t0 = cv2.getTickCount()
edges = cv2.Canny(img, 50, 150)
t1 = cv2.getTickCount()
print(f"Canny: {(t1 - t0) / cv2.getTickFrequency() * 1000:.2f} ms")

# set USE_AVX / thread count
cv2.setNumThreads(4)
print(cv2.getNumThreads())

Événements souris

setMouseCallback enregistre un handler pour les événements souris d'une fenêtre nommée — utile pour la sélection interactive de ROI, les outils d'annotation et les petites apps de peinture. Événements courants : LBUTTONDOWN, LBUTTONUP, MOUSEMOVE, RBUTTONDOWN. Le handler doit être une fonction de premier niveau (ou globale) ; les globales sont la façon standard de partager l'état car la signature du callback est fixe.

opencv
import cv2
import numpy as np

drawing = False
ix, iy = -1, -1

def on_mouse(event, x, y, flags, param):
    global drawing, ix, iy
    if event == cv2.EVENT_LBUTTONDOWN:
        drawing = True
        ix, iy = x, y
    elif event == cv2.EVENT_MOUSEMOVE and drawing:
        cv2.rectangle(img, (ix, iy), (x, y), (0, 255, 0), -1)
    elif event == cv2.EVENT_LBUTTONUP:
        drawing = False
        cv2.rectangle(img, (ix, iy), (x, y), (0, 255, 0), -1)

img = np.zeros((512, 512, 3), np.uint8)
cv2.namedWindow("canvas")
cv2.setMouseCallback("canvas", on_mouse)

while True:
    cv2.imshow("canvas", img)
    if cv2.waitKey(1) & 0xFF == ord('q'):
        break
cv2.destroyAllWindows()

Trackbar

Les trackbars permettent de régler les paramètres de façon interactive sans relancer le script — inestimables pour trouver de bons seuils, tailles de noyaux et plages HSV. Le callback est appelé à chaque changement (un no-op convient si vous sondez getTrackbarPos dans la boucle principale). Les trackbars se créent sur une fenêtre nommée et se lisent avec getTrackbarPos(window, name).

opencv
import cv2
import numpy as np

def nothing(x):
    pass

img = np.zeros((300, 512, 3), np.uint8)
cv2.namedWindow("image")

# create trackbars
cv2.createTrackbar("R", "image", 0, 255, nothing)
cv2.createTrackbar("G", "image", 0, 255, nothing)
cv2.createTrackbar("B", "image", 0, 255, nothing)
cv2.createTrackbar("switch", "image", 0, 1, nothing)

while True:
    cv2.imshow("image", img)
    if cv2.waitKey(1) & 0xFF == 27:    # Esc to quit
        break

    r = cv2.getTrackbarPos("R", "image")
    g = cv2.getTrackbarPos("G", "image")
    b = cv2.getTrackbarPos("B", "image")
    s = cv2.getTrackbarPos("switch", "image")

    if s == 0:
        img[:] = 0
    else:
        img[:] = [b, g, r]

cv2.destroyAllWindows()

Sélecteur de ROI

selectROI ouvre une fenêtre interactive où l'utilisateur tire un rectangle et presse Entrée/Espace — bien plus simple qu'écrire son propre callback souris. Appuyez « c » pour annuler (retourne tout à zéro). selectROIs permet de choisir plusieurs rectangles l'un après l'autre. Le tuple retourné est (x, y, w, h) ; rognez avec img[y:y+h, x:x+w].

opencv
import cv2

img = cv2.imread("photo.jpg")

# built-in ROI selector (drag a rectangle)
roi = cv2.selectROI("select", img, showCrosshair=True, fromCenter=False)
cv2.destroyAllWindows()

x, y, w, h = roi
cropped = img[y:y+h, x:x+w]

# multiple ROIs
rois = cv2.selectROIs("select", img, showCrosshair=True, fromCenter=False)
for r in rois:
    x, y, w, h = r
    cv2.imshow("roi", img[y:y+h, x:x+w])
    cv2.waitKey(0)
cv2.destroyAllWindows()

Pièges courants

Ces cinq pièges causent la majorité des bugs OpenCV : confusion BGR/RGB (rouge et bleu inversés), débordement uint8 (artefacts sombres/lumineux), ordre des coordonnées (ROI décalées d'une unité), None de fichier manquant (les opérations suivantes crashent avec des erreurs obscures) et oubli de waitKey (les fenêtres ne se rafraîchissent pas). Intériorisez-les tôt — chaque développeur OpenCV tombe au moins une fois sur chacun.

opencv
import cv2
import numpy as np

# 1. BGR vs RGB — imshow expects BGR; matplotlib expects RGB
img = cv2.imread("p.jpg")
# plt.imshow(cv2.cvtColor(img, cv2.COLOR_BGR2RGB))   # correct
# plt.imshow(img)                                     # colors look wrong

# 2. uint8 overflow — use cv2 ops or upcast
a = np.array([200], np.uint8)
print(a + 100)        # [44]   (wraps, WRONG)
print(cv2.add(a, 100))  # [[255]] (saturates, RIGHT)

# 3. (x, y) vs (row, col) — drawing uses (x,y), NumPy uses [y,x]
cv2.rectangle(img, (10, 20), (110, 120), (0, 255, 0), 2)  # x=10..110
roi = img[20:120, 10:110]   # rows 20..120, cols 10..110 (same region)

# 4. None returned by imread when the file is missing
img = cv2.imread("missing.jpg")
if img is None:
    raise FileNotFoundError("could not read image")

# 5. waitKey is mandatory for imshow to actually render
cv2.imshow("img", img)
cv2.waitKey(1)   # without this, the window may stay blank

Was this helpful?

Learning path

Learn from scratch

Learn this language from the ground up with structured lessons.