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.
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.
# 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 npImage 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).
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-299Accè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.
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 channelTypes 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.
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) # uint8Capture 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.
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).
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.
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.
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 differFré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.
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()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.
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.
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.
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.
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.
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.
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)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.
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.
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.
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.
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.
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] = 0Saturation 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.
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 -> 44Transformations 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).
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) # enlargingRotation
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.
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.
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.
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.
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.
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)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.
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.
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.
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.
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.
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.
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)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.
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.
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.
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).
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.
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:
breakHit-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.
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")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.
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.
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.
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).
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.
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)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.
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é.
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.
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.
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.
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.
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)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.
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.
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é.
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.
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.
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é.
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)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.
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.
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.
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.
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.
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.
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)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.
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.
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.
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.
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.
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)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.
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.
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é.
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.
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.
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.
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)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.
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.
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.
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.
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.
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)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.
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.
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.
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.
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).
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)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.
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.
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 classifierAppariement 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.
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.
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.
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 suppressionSegmentation 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.
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.
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 ».
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 redFlood 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.
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 1Composantes 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.
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.
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)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).
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.
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.
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.
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.
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 cornerProfondeur 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.
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.
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.
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.
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.
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()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).
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.
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).
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].
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.
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 blankSnippets OpenCV associés
Copy-paste ready code for common tasks.
Read and Write Images
Load, display, and save images in various formats.
Resize and Crop
Resize with interpolation and crop regions of interest.
Color Conversion
Convert between BGR, RGB, HSV, and grayscale.
Blur and Filter
Smooth and sharpen images with kernels.
Edge Detection
Detect edges with Canny, Sobel, and Laplacian.
Contours
Find, draw, and measure contours.
Face Detection
Detect faces with a Haar cascade classifier.
Threshold
Apply binary, adaptive, and Otsu thresholding.
Was this helpful?