Erste Schritte
Bilder lesen, anzeigen & speichern
OpenCV liest Bilder in BGR-Reihenfolge (nicht RGB) — eine häufige Falle beim Interop mit matplotlib oder PIL. cv2.waitKey(0) blockiert, bis eine Taste gedrückt wird; immer destroyAllWindows() aufrufen, um Fenster zu schließen. JPEG-Qualität ist 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])Installieren & Importieren
opencv-python liefert nur die Hauptmodule; opencv-contrib-python ergänzt weitere (oft patentbelastete) Module wie SIFT/SURF und ArUco. In Servern/Docker die headless-Variante verwenden, um keine X11-Abhängigkeiten zu ziehen. Trotz des Namens cv2 importiert sich OpenCV 4.x weiterhin als 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 npBild als NumPy-Array
OpenCV-Bilder sind NumPy-Arrays, alles, was du über NumPy wei ßt, gilt also. Die Koordinatenkonvention ist img[y, x] (Zeile, Spalte) — das Gegenteil der (x, y)-Bildkoordinaten, eine häufige Bugquelle. Farbbilder sind (H, W, 3) in BGR; Graustufen (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-299Pixel-Zugriff & ROI
Pixelweiser Zugriff über img[y, x] ist langsam und in Schleifen unüblich — immer NumPy-Slicing bevorzugen. .copy() bei ROI-Zuweisung, damit spätere Änderungen der Quelle nicht einbluten. img[:, :, channel] zu ändern ist der schnellste Weg, auf einem einzelnen Farbkanal zu operieren.
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 channelDatentypen & Konvertierung
Die meisten OpenCV-Funktionen erwarten uint8 (0-255), aber Algorithmen wie SIFT, Optical Flow und Kantenerkennung brauchen oft float32. Nach Subtraktion nie direkt mit .astype() casten — uint8-Überlauf macht aus -1 eine 255. cv2.absdiff verwenden oder erst nach float konvertieren. Vor cv2.imwrite / imshow immer zurück auf uint8 casten.
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) # uint8Video-Capture
Webcam öffnen
VideoCapture(0) öffnet die Standard-Webcam; 1, 2... für weitere Kameras. Immer cap.release() aufrufen, um das Gerät freizugeben — vergessen kann es die Kamera für andere Apps blockieren. waitKey(1) wartet ~1 ms; der & 0xFF-Trick stellt Kompatibilität auf 64-Bit-Systemen sicher, wo waitKey mehr als 8 Bits liefert.
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()Videodatei lesen
CAP_PROP_FRAME_COUNT ist oft annähernd und bei manchen Codecs unzuverlässig — nicht für exaktes Suchen darauf verlassen. waitKey(int(1000/fps)) spielt mit ungefähr korrekter Geschwindigkeit; für präzises Timing eine echte Uhr nutzen. Manche komprimierte Videos öffnen sich ohne das richtige Backend (FFmpeg) nicht.
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()Video speichern / schreiben
Der FourCC-Code ist plattform- und codecabhängig: 'mp4v' ist weit portabel, 'XVID' erzeugt .avi, 'avc1' gibt H.264 (evtl. ohne proprietäre Codecs nicht verfügbar). Die an VideoWriter übergebene Frame-Größe MUSS zu den geschriebenen Frames passen, sonst ist die Datei korrupt. Immer out.release() aufrufen, um zu spülen und die Datei zu schließen.
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()Kameraeinstellungen
Kameraeigenschaften sind hardware- und treiberabhängig — viele Webcams ignorieren nicht unterstützte Einstellungen stillschweigend oder springen auf den nächsten gültigen Wert, also den tatsächlichen Wert immer zurücklesen. CAP_PROP_EXPOSURE nutzt log2 der Sekunden (-4 = 1/16 s). Auto-Belichtung muss deaktiviert werden (auf 1 gesetzt), bevor manuelle Belichtung bei den meisten Kameras greift.
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 differFramerate & Timing
cap.get(CAP_PROP_FPS) liefert die konfigurierte FPS, nicht die tatsächliche Aufnahmerate — mit einer echten Uhr messen. Ein gleitender Durchschnitt über 30 Frames glättet Jitter. Die größten FPS-Killer sind cv2.imshow (GUI-Thread) und per-Frame cv2.imwrite; beim Benchmarking die Anzeige abschalten. Für deterministisches Timing Frames in einem Thread sammeln und aus einer Queue verarbeiten.
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()Zeichnen
Linie & Rechteck
Alle Zeichenfunktionen mutieren das Bild in place — eine Kopie übergeben, wenn du das Original behalten willst. Koordinaten sind (x, y), entgegengesetzt zu NumPys [y, x]-Indexierung. Farben sind BGR-Tupel. thickness=-1 für gefüllte Formen und cv2.LINE_AA für glatte (antialiaste) Linien an diagonalen Kanten.
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)Kreis & Ellipse
Der axes-Parameter der ellipse ist (halbeBreite, halbeHöhe) — volle Breite ist 2 * axes[0]. angle rotiert die ganze Ellipse; startAngle/endAngle zeichnen Teilarcs (0° = rechts, gegen den Uhrzeigersinn). Teilarcs zu zeichnen ist der Standardweg, Tortendiagramm-Segmente oder Bewegungsrichtungs-Indikatoren zu rendern.
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)Polygon & Polylines
polylines nimmt eine Liste von Punkt-Arrays, mehrere Polygone in einem Aufruf also möglich. Das Punkte-Array muss int32 sein und auf (-1, 1, 2) umgeformt. fillPoly für gefüllte Formen; für transluzente Füllungen auf ein Overlay zeichnen und mit addWeighted mischen. Das isClosed-Flag verbindet den letzten Punkt zurück zum ersten.
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)Text
OpenCVs eingebaute Schriften sind Hershey-Vektorfonts — sie unterstützen keine CJK-/chinesischen Zeichen. Für Nicht-Latein-Text mit PIL (Pillow) ImageFont rendern und zurückkonvertieren oder cv2.freetype aus opencv-contrib nutzen. getTextSize liefert ((Breite, Höhe), Grundlinie) — nützlich, um Text zu zentrieren oder eine Hintergrundbox dahinter zu zeichnen.
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)Pfeil & Marker
arrowedLines tipLength ist ein Anteil der Linienlänge, längere Pfeile haben also proportional größere Spitzen — für einheitliche Pfeilspitzengrößen explizit setzen. drawMarker ist praktisch, um Schlüsselpunkte hervorzuheben (z. B. erkannte Features oder Ecken); MARKER_TILTED_CROSS ergibt ein X-förmiges Zeichen.
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 & Annotation
Die Overlay-Technik (auf eine Kopie zeichnen, dann addWeighted) ist der Standardweg für transluzente Füllungen — OpenCV hat kein natives Alpha für Formen. Soliden Text IMMER nach dem Mischen zeichnen, damit er scharf bleibt; Text vor dem Mischen aufs Overlay zu zeichnen macht ihn unscharf. Dieses Muster ist überall in der Erkennungs-/Segmentierungsvisualisierung.
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)Bild-Arithmetik
Addieren & Subtrahieren
OpenCVs cv2.add sättigt bei 255 (250 + 10 = 255), NumPys + umläuft (250 + 10 = 8 wegen uint8-Überlauf). Für Bilder immer cv2.add / cv2.subtract — Umlauf erzeugt sichtbare Schwarz-/Weiß-Artefakte. absdiff ist das Arbeitstier für Hintergrundsubtraktion und Bewegungserkennung.
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)Mischen & addWeighted
addWeighted verlangt identische Größe und dtype beider Bilder — zuerst resizen. Der gamma-Term ergänzt eine Konstante zu jedem Pixel, nützlich für Helligkeitskontrolle. Das klassische Überblenden/zarte Auflösen zwischen zwei Bildern ist nur addWeighted mit Alpha, das von 0 auf 1 fährt.
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)Bitweise Operationen
Bitweise Ops sind der Standardweg, eine Maske anzuwenden: cv2.bitwise_or(src, dst, mask=mask) kopiert src in dst nur dort, wo die Maske nicht Null ist. Die Maske muss ein einkanaliges 8-Bit-Bild sein, in dem Nicht-Null 'behalten' heißt. Das Fundament von ROI-Extraktion und Hintergrundersetzung.
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)Bilddifferenz & Bewegung
Frame-Differenzbildung ist der einfachste Bewegungsdetektor: die absolute Differenz aufeinanderfolgender Frames schwellig machen. Er versagt bei Kamerabewegung und ignoriert langsame Bewegung — für echte Systeme Hintergrundsubtraktion (cv2.createBackgroundSubtractorMOG2) oder Optical Flow nutzen. Morphologisches Öffnen entfernt Rauschen; Dilation verschmilzt nahe Blobs.
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 & Maskierung
bitwise_and mit einer Maske ist der idiomatische Weg, unregelmäßige Regionen zu extrahieren. Boolesche NumPy-Indexierung (img[mask]) ist flexibler, liefert aber ein flaches Pixel-Array, kein geformtes Bild. ROIs, die du wiederverwenden willst, immer .copy() — Slicing liefert eine View, die das Original aliasiert.
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] = 0Sättigung vs. Umlauf
Die uint8-Überlauffalle: NumPy umläuft (300 -> 44), OpenCV sättigt (300 -> 255). Bei jeder Arithmetik, die 0-255 überschreiten kann, entweder cv2.add/subtract nutzen oder erst auf int16/float32 hochcasten und zurück clippen. cv2- und NumPy-Ops in derselben Pipeline zu mischen ist die Ursache Nummer 1 für mysteriöse dunkle/helle Pixelartefakte.
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 -> 44Geometrische Transformationen
Resize / Skalieren
INTER_AREA ist am besten zum Verkleinern (vermeidet Aliasing), INTER_CUBIC oder INTER_LINEAR zum Vergrößern. INTER_NEAREST ist am schnellsten, aber blockig — für Label-/Maskenbilder, wo keine neuen Pixelwerte eingeführt werden dürfen. Das dsize-Tupel ist (Breite, Höhe), das Gegenteil von img.shape, das (Höhe, Breite) ist.
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 ist viel schneller als warpAffine für 90°-Vielfache. getRotationMatrix2Ds Winkel ist in Grad, positiv = gegen den Uhrzeigersinn. Um ohne Beschneidung zu rotieren, die Bounding-Box (new_w, new_h) neu berechnen und die Rotationsmatrix verschieben — sonst werden die Ecken eines großen gedrehten Bildes abgeschnitten.
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))Affine Transformation
Eine affine Transformation erhält Parallelität und Distanzverhältnisse — definiert durch 3 Punktentsprechungen (6 Freiheitsgrade). warpAffine nutzt implizit eine Vorwärtsmapping via Inverssuche, M mapt also src->dst, aber die Funktion invertiert intern. Mit borderMode=BORDER_REFLECT oder BORDER_CONSTANT steuern, wie außerhalb liegende Regionen gefüllt werden.
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)Perspektivische Transformation
Perspektive (Homographie) ist durch 4 nicht-kollineare Punktpaare definiert — 8 Freiheitsgrade. Das ist die Standard-'Dokumentenscanner'-Transformation: die 4 Ecken einer Karte/eines Blattes im Foto wählen und auf ein Rechteck warp. getPerspectiveTransform braucht exakt 4 Punkte; für einen überbestimmten Fit cv2.findHomography mit RANSAC nutzen.
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))Flip & Spiegel
flip ist eine billige In-Memory-Operation — viel schneller als warpAffine. Die flipCode-Vorzeichenkonvention: positiv kippt horizontal, 0 vertikal, negativ beides. cv2.transpose tauscht Achsen und wird manchmal als schnelle 90°-Rotation in Kombination mit einem Flip genutzt.
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 (eigene Abbildung)
remap ist die allgemeinste geometrische Transformation — resize, Rotation und sogar Fass-/Linsenverzerrungskorrektur lassen sich alle als remap ausdrücken. Die Maps immer mit NumPy-Vektorisierung bauen, nicht mit Python-Schleifen (die Schleifenversion oben ist nur zur Illustration — sie ist ~100x langsamer). INTER_LINEAR ist der Standard; für Sub-Pixel-Genauigkeit an Kanten 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)Bildfilterung
Durchschnittsblur (Box-Filter)
Durchschnittsblur ist der einfachste Tiefpassfilter — er ersetzt jedes Pixel durch den Mittelwert seiner Nachbarschaft. Kernel müssen ungerade und positiv sein. Größere Kernel bluren mehr, zerstören aber auch schneller Detail. Verwenden, wenn du gezielt gleichmäßige Gewichtung willst; bei natürlichen Bildern ist Gauß-Blur fast immer die bessere Wahl.
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)Gauß-Blur
Gauß-Blur ist der Standard-Glättungskern — er gewichtet Nachbarn nach einer Gaußverteilung und erhält Kanten besser als ein Box-Filter. Bei ksize=(0,0) und sigmaX berechnet OpenCV die Kernelgröße automatisch. Gauß-Blur ist ein Pflicht-Vorlauf vor Canny, Downsampling und Laplacian, um Rauschverstärkung zu unterdrücken.
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)Median-Blur
Median-Blur ist der Standardfilter für Salz-und-Pfeffer-(Impuls-)Rauschen — er ersetzt jedes Pixel durch den Median seiner Nachbarschaft, isolierte Ausreißer werden also entfernt statt verteilt. Anders als Gauß erhält er Kanten gut. Die Kernelgröße muss ungerade sein. Er ist langsamer als Gauß/Box, weil Sortierung im Spiel ist.
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)Bilateraler Filter
Bilaterale Filterung glättet flache Regionen und erhält scharfe Kanten — ein nichtlinearer, kantenerhaltender Filter, der Nachbarn sowohl nach räumlicher Nähe als auch nach Farbähnlichkeit gewichtet. Viel langsamer als Gauß (oft 10x). Wiederholte Anwendung ist der klassische 'Cartoonifier'-Vorverarbeitungsschritt; große sigmaColor-Werte mischen über mehr Farben.
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)Schärfen (Kernel)
Schärfkerne betonen hohe Frequenzen — verstärken aber auch Rauschen, also nach der Entrauschung anwenden. Der klassische 3x3-Schärfkern summiert zu 1 (erhält Helligkeit); eine Summe > 1 erhellt. Die Unsharp-Mask-Technik (eine blurre Kopie abziehen) ist besser steuerbar und das, was die meisten Fotoeditoren tatsächlich nutzen.
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)Eigener Kernel (filter2D)
filter2D wendet einen beliebigen Korrelationskern an — ddepth=-1 erhält die Quelltiefe. Kernel dürfen float sein für negative Koeffizienten; wird das Ergebnis negativ, auf ddepth=cv2.CV_16S oder CV_32F wechseln und mit convertScaleAbs zurück. Trennbare Kernel (äußeres Produkt von 1D-Kernen) sind über sepFilter2D viel schneller.
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)Morphologische Operationen
Erosion & Dilation
Erosion schrumpft Vordergrund-(weiße-)Regionen und entfernt kleine Rauschpunkte; Dilation vergrößert sie und füllt kleine Löcher. Die Kernelform zählt: RECT für allgemeine Nutzung, ELLIPSE für rundere Formen, CROSS zum Verdünnen/Verbinden entlang der Achsen. iterations=N wiederholt die Operation N-mal, äquivalent zu einem größeren Kernel.
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))Öffnen & Schließen
Öffnen (erode→dilate) entfernt kleine helle Punkte, ohne die Größe größerer Objekte zu ändern. Schließen (dilate→erode) füllt kleine dunkle Löcher. Beide sind idempotent — zweimal anwenden entspricht einmal. Das klassische Entrauschungsmuster ist erst schließen, dann öffnen (oder umgekehrt), um beide Defektarten zu behandeln.
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)Morphologischer Gradient
Der morphologische Gradient (Dilation - Erosion) erzeugt eine dicke Kontur der Objektgrenzen — nützlich als schneller Kantendetektor oder als Maske fürs Segementieren. Anders als Canny liefert er gefüllte, breite Kanten — gut, um Regionen hervorzuheben statt exakte Kantenpositionen zu messen.
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 & Black Hat
Top-hat extrahiert kleine helle Strukturen, kleiner als der Kernel (z. B. Text auf einem dunklen Dokument); black-hat extrahiert kleine dunkle Strukturen. Gemeinsam dienen sie Schatten-/Glanzlicht-Extraktion und als schneller Ausgleicher ungleichmäßiger Beleuchtung (der Divide-by-Background-Trick ist bei Dokumentenscannern üblich).
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)Skelettierung
Morphologische Skelettierung verdünnt eine binäre Form auf eine 1-Pixel-breite Mittellinie — nützlich für OCR, Fingerabdruck- und Gefäßanalyse. Die iterative erode-subtract-open-Schleife läuft, bis das Bild leer ist. Für Produktion ist scikit-images medial_axis oder thinning schneller und liefert sauberere Ergebnisse.
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 ist der morphologische Musterabgleicher — er findet exakte Konfigurationen aus Vordergrund- und Hintergrundpixeln, nützlich, um bestimmte Formen wie Ecken oder T-Kreuzungen zu erkennen. Der Kernel nutzt 1 für erforderlichen Vordergrund, -1 für erforderlichen Hintergrund, 0 für egal. Nischig, aber unschlagbar für exakte Musterlokalisierung.
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")Kantenerkennung
Canny-Kantendetektor
Canny ist der meistgenutzte Kantendetektor: Gauß-Glättung → Sobel-Gradienten → Nicht-Maximum-Unterdrückung → Hysterese (zwei Schwellen). Pixel über dem hohen Schwellwert sind Kanten; die zwischen niedrig und hoch nur, wenn mit einer starken Kante verbunden. Der Auto-Schwellwert-Trick (Median × 0.7/1.3) funktioniert gut bei vielfältigen Bildern.
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)Sobel-Operator
Sobel berechnet die erste Ableitung — ddepth=cv2.CV_64F (oder CV_16S) verwenden, um negative Gradienten zu erfassen, sonst macht uint8-Überlauf dunkle-zu-helle-Übergänge unsichtbar. ksize=3 ist Standard; ksize=5 liefert glattere, aber breitere Kanten. Die Magnitude (sqrt(sx²+sy²)) ist die Basis von Canny und vieler Feature-Detektoren.
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 ist die zweite Ableitung — sehr rauschempfindlich, also immer zuerst blurren. Er erkennt Nullstellen-Durchgänge (Vorzeichenwechsel) und liefert dünne, präzise Kanten, aber keine Richtung. Am häufigsten in der Marr-Hildreth-Kantenerkennung und als 'L'-Kanaleingabe beim Bildschärfen (Unsharp Mask). CV_64F verwenden, weil die zweite Ableitung stark negativ ausschlägt.
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)Scharr-Filter
Scharr ist eine für 3x3-Fenster entworfene Sobel-Variante — wenn ein kleiner Kernel nötig ist, liefert er genauere Gradientenrichtungen als Sobel ksize=3. Bei größeren Kerneln (5x5, 7x7) ist Sobel in Ordnung. cv2.Sobel mit ksize=-1 entspricht Scharr. Scharr wird bevorzugt, wenn die Gradientenrichtung zählt (HOG, Kantenorientierung).
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)Kantenerkennungs-Pipeline
Die Pipeline Graustufen → entrauschen → Canny → dilate → findContours deckt einen riesigen Anteil praktischer Kantenaufgaben ab. Dilation vor dem Konturfinden schließt gebrochene Kanten, die sonst ein Objekt in viele teilen würden. Das Tuning der Canny-Schwellwerte und der Entrauschungs-Kernelgröße ist, wo die meiste Ingenieursarbeit hingeht.
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)Konturen
Konturen finden
findContours mutiert das Quellbild in OpenCV 3.x — eine Kopie übergeben, wenn du das Binärbild danach brauchst. RETR_EXTERNAL liefert nur die äußersten Konturen (am schnellsten); RETR_TREE die volle Hierarchie für verschachtelte Formen (Löcher in Objekten). CHAIN_APPROX_SIMPLE verwirft redundante Punkte entlang gerader Linien und spart Speicher.
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)Konturen zeichnen
drawContours(image, contours, contourIdx, color, thickness): contourIdx=-1 zeichnet alle; ein konkreter Index zeichnet eine. thickness=-1 füllt die Kontur. Auf ein leeres Bild zeichnen ist der Standardweg, eine Konturmaske für nachgelagerte Operationen wie Mittelfarbe oder maskiertes Histogramm zu bauen.
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)Kontureigenschaften
contourArea ist in Pixeln und ignoriert Löcher (für Nettofläche die Kontur mit RETR_CCOMP-Hierarchie nutzen). Das moments-Dictionary liefert den Schwerpunkt (m10/m00, m01/m00) — gegen Division durch Null absichern, wenn m00 gleich 0 ist (degenerierte Konturen). Seitenverhältnis und Ausdehnung sind die einfachsten Formdeskriptoren fürs Formklassifizieren.
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}")Bounding-Rectangles
boundingRect gibt eine achsenparallele Box (schnell, einfach); minAreaRect das kleinste rotierte Rechteck (nützlich, um echte Orientierung/Größe eines Objekts zu messen). boxPoints wandelt das rotierte Rechteck in 4 Eckpunkte um, die du an drawContours übergeben kannst. minEnclosingCircle ist der kleinste Kreis, der die Kontur enthält.
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)Konturapproximation
approxPolyDP vereinfacht eine Kontur zu einem Polygon mit weniger Ecken über den Douglas-Peucker-Algorithmus. Das epsilon (typisch 1-5 % des Umfangs) steuert die Toleranz: kleiner behält mehr Detail. Ecken zu zählen ist der klassische handgestrickte Formklassifikator — Dreieck=3, Rechteck=4, Kreis=viele.
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)Konvexe Hülle & Defekte
Die konvexe Hülle ist die kleinste konvexe Form, die die Kontur umschließt — nützlich, um die Kompaktheit eines Objekts zu messen und für Hand-/Fingererkennung über Konvexitätsdefekte. Die Tiefe jedes Defekts misst, wie weit die Kontur relativ zur Hülle 'nach innen' eintaucht; tiefe Defekte an einer Handsilhouette entsprechen typisch Lücken zwischen Fingern.
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)Schwellenwertbildung
Einfacher Schwellenwert
THRESH_BINARY: darüber->255, darunter->0. THRESH_TRUNC: darüber->auf thresh gekappt, darunter->unverändert. THRESH_TOZERO: darüber->unverändert, darunter->0. Das zurückgegebene ret entspricht dem Eingabeschwellwert bei plainer Schwellenwertbildung, wird aber bei Otsu/Triangle bedeutsam. Den Typ danach wählen, wie außerhalb liegende Pixel behandelt werden sollen.
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)Adaptiver Schwellenwert
Adaptive Schwellenwertbildung berechnet für jedes Pixel einen eigenen Schwellwert aus seiner lokalen Nachbarschaft — essenziell für Bilder mit ungleichmäßiger Beleuchtung (z. B. fotografierte Dokumente). blockSize muss ungerade sein (typisch 11-31) und größer als die Merkmalsgröße. C zieht eine Konstante vom lokalen Mittel ab; erhöhen, um schwach kontrastiges Rauschen zu unterdrücken.
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)Otsus Methode
Otsus Methode findet den optimalen globalen Schwellwert, indem sie die Varianz zwischen Vordergrund- und Hintergrundklassen maximiert — thresh=0 übergeben und das Flag THRESH_OTSU ergänzen. Zuerst immer blurren; Otsu ist empfindlich auf Histogrammrauschen. Die Triangle-Methode funktioniert besser bei Bildern mit einem einzigen dominanten Peak (z. B. Mikroskopie). Das zurückgegebene ret ist der berechnete Schwellwert.
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}")Farbschwellenwert (inRange)
inRange ist das Standardwerkzeug zur Farbsegmentierung — zuerst nach HSV konvertieren, weil es Farbe (Hue) von Helligkeit trennt und Schwellwerte damit robust gegen Lichtwechsel sind. Die rote Hue umrundet 0/180, du brauchst also zwei per ODER verbundene Masken. Vor inRange immer blurren, um Rauschpunkte in der Maske zu mindern.
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)Schwellenwert-Pipeline
Die Pipeline entrauschen → Schwellenwert → Morphologie bewältigt die meisten Binärisierungsaufgaben. Otsu bei gleichmäßiger Beleuchtung, adaptiv bei ungleichmäßiger. Das morphologische erst-schließen-dann-öffnen entfernt innere Löcher wie äußere Punkte. Die binäre Maske immer prüfen — Schwellwertparameter sind fast immer bildspezifisch und brauchen Tuning pro Datensatz.
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)Binärisierung für OCR
Für OCR schlägt adaptives Gauß auf fotografierten Dokumenten fast immer das globale Otsu, wegen ungleichmäßiger Beleuchtung. blockSize an die Zeichenhöhe anpassen (Faustregel: 1-2× Strichbreite × 4). Die meisten OCR-Engines (Tesseract) bevorzugen schwarzen Text auf weißem Grund — umkehren, wenn dein Binärbild umgekehrt ist.
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)Farbräume
BGR / RGB / Grau
OpenCV liest Bilder standardmäßig als BGR; die meisten anderen Bibliotheken (matplotlib, PIL, scikit-image) nutzen RGB. cvtColor zu vergessen ist die häufigste Ursache für 'rot und blau vertauschte' Bilder. Die Graustufenkonvertierung nutzt Wahrnehmungsgewichte (Y = 0.299R + 0.587G + 0.114B), kein einfacher Durchschnitt.
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 nach HSV
OpenCVs HSV nutzt H in 0-179 (nicht 0-360), damit es in uint8 passt — eine häufige Quelle von um-Faktor-2-Bugs beim Portieren von Code aus anderen Bibliotheken. S und V sind 0-255. HSV ist der Standardraum für farbbasierte Segmentierung, weil Hue ungefähr invariant gegen Helligkeitswechsel ist — für Objekt-Tracking nach Farbe verwenden.
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 nach LAB
CIELAB approximiert menschliche Wahrnehmung — gleiche numerische Änderungen sehen ungefähr gleich unterschiedlich aus, deshalb wird es für Farbdifferenz-Metriken (ΔE) genutzt. Der L-Kanal kodiert nur Helligkeit, L zu bearbeiten ist also der sauberste Weg, ein Bild aufzuhellen, ohne Farben zu verschieben. OpenCVs LAB nutzt 0-255 für alle Kanäle, nicht die üblichen 0-100 für 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)Farb-Tracking (HSV)
HSV-basiertes Farb-Tracking ist der einfachste Objekt-Tracker — Hue-Bereich wählen, Schwellwert bilden, größten Blob finden. Er versagt bei schlechter Beleuchtung (niedrige Sättigung), bei ähnlich farbigen Hintergrundobjekten und auf reflektierenden Flächen. Für robustes Tracking mit camshift/meanshift kombinieren (nutzt eine Hue-Histogramm-Rückprojektion) oder mit einem Kalman-Filter die Bewegung glätten.
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()Kanäle splitten & verschmelzen
split/merge sind bequem, aber langsamer als NumPy-Indexierung — img[:, :, 0] ist der blaue Kanal, und ihn zu ändern ist schneller als split. Kanäle zum Mergen immer in der korrekten Reihenfolge des Ziel-Farbraums übergeben. Der 'zwei Kanäle auf Null setzen'-Trick ist der klassische Weg, den Beitrag eines einzelnen Farbkanals zu visualisieren.
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])Weitere Farbräume
YCrCb trennt Luminanz (Y) von Chroma (Cr, Cb) — die Basis von JPEG- und MPEG-Kompression, die Chroma-Detail verwirft, weil Menschen farblich weniger empfindlich sind als hell. HLS unterscheidet sich von HSV darin, dass Weiß bei L=1 liegt unabhängig von der Sättigung, was HLS für manche Schattierungseffekte besser macht. Den Raum wählen, der deine Operation invariant gegenüber macht, was dich nicht interessiert.
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)Histogramme
Histogramm berechnen
calcHist nimmt eine Liste von Bildern, eine Liste von Kanälen, eine optionale Maske (None = ganzes Bild), die Bin-Anzahl und den Wertebereich. Für mehrdimensionale Histogramme (z. B. 2-D-Hue-Sättigung) zwei Kanäle und zwei Bin-Größen übergeben — genutzt in der Histogramm-Rückprojektion für Farb-Tracking. Das Histogramm jedes Kanals wird unabhängig berechnet.
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])Histogramm plotten
Matplotlib ist der einfachste Weg, Histogramme zu visualisieren — aber BGR vor der Legende nach RGB konvertieren, sonst matchen deine Plot-Farben nicht den Kanal-Labels. Ein nach links verschobenes Histogramm ist ein dunkles Bild, nach rechts ein helles; eine schmale Spitze heißt niedriger Kontrast. Damit Belichtungs- und Weißabgleich-Probleme diagnostizieren.
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()Histogramm-Equalisierung
Histogramm-Equalisierung streckt Pixelintensitäten über die vollen 0-255 — großartig für kontrastarme Bilder, kann aber Glanzlichter ausbrennen und Rauschen verstärken. NIE alle drei BGR-Kanäle direkt equalisieren — es verschiebt Farben. Immer in einen Luminanz-/Chrominanz-Raum konvertieren (YCrCb, LAB, HSV), die Luminanz equalisieren und zurückkonvertieren.
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 (adaptive Equalisierung)
CLAHE ist die produktionsreife Alternative zur globalen Equalisierung — es arbeitet auf kleinen Kacheln, funktioniert also bei ungleichmäßiger Beleuchtung, und clipLimit deckelt die Kontrastverstärkung, um Rauschen nicht zu sprengen. tileGridSize 8x8 ist der Standard; kleinere Kacheln passen sich lokaler an. Die erste Wahl für medizinische Bildgebung und Dokumentverbesserung.
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)Histogramm-Rückprojektion
Histogramm-Rückprojektion beantwortet 'wo sehen Pixel aus wie die Farbverteilung meiner ROI?'. Ein 2-D-Hue-Sättigungs-Histogramm aus einer Stichprobe bauen, dann auf ein Zielbild zurückprojizieren, um eine Wahrscheinlichkeitskarte zu bekommen. Das ist die Basis des meanShift/camShift-Tracking — weit robuster als ein fester HSV-Bereich, weil es die echte Farbverteilung des Ziels lernt.
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)Feature-Erkennung
Harris-Eckendetektor
Harris erkennt Ecken, indem es prüft, ob das Verschieben eines kleinen Fensters in irgendeine Richtung eine große Intensitätsänderung verursacht — Ecken ändern sich in alle Richtungen, Kanten in eine, flache Regionen in keine. Die Ausgabe ist eine Eckantwort-Karte; relativ zum Maximum schwellig machen (z. B. 0.01 * max). blockSize ist die Nachbarschaft für die Strukturtensor-Berechnung.
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 verbessert Harris, indem es min(Eigenwert1, Eigenwert2) als Score nutzt — das liefert stabilere Ecken fürs Tracking. maxCorners begrenzt die Anzahl; qualityLevel ist ein Anteil der stärksten Eckantwort (0.01 = 1 % der besten); minDistance erzwingt räumliche Trennung zwischen erkannten Ecken. Das ist die Standard-Eingabe für den Lucas-Kanade-Optical-Flow-Tracker.
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 (skaleninvariante Features)
SIFT findet skalen- und rotationsinvariante Keypoints mit einem 128-D-Deskriptor je Stück — robust gegen Beleuchtung, Blickwinkel und teilweise Verdeckung. Jahrelang patentierte es sich, in OpenCV 4.4 wurde es frei. SIFT für hochgenaues Matching verwenden, wo Tempo zweitrangig ist. DRAW_RICH_KEYPOINTS zeichnet Skalierung und Orientierung jedes Keypoints.
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 kombiniert den FAST-Keypoint-Detektor mit dem BRIEF-Deskriptor — beide patentfrei und ~10x schneller als SIFT, was ORB zur Standardwahl für Echtzeit-Matching auf Mobile/Embedded macht. Deskriptoren sind binär (32 Bytes vs. SIFTs 128 Floats), das Matching nutzt Hamming-Distanz. Etwas weniger robust als SIFT bei Skalierung/Rotation, aber hervorragend für den Preis.
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)FAST-Detektor
FAST prüft, ob ein Kreis aus 16 Pixeln um einen Kandidaten N aufeinanderfolgende Pixel hat, die alle heller oder alle dunkler als das Zentrum sind — extrem schnell, weil er kurzschließt. Er liefert nur Keypoints, keine Deskriptoren (für Deskriptoren BRIEF oder ORB nutzen). Niedrigerer Schwellwert = mehr (und verrauschtere) Ecken; Nicht-Maximum-Unterdrückung entfernt Duplikate an lokalen Maxima.
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 (Maximally Stable Extremal Regions)
MSER findet Regionen, die über einen Bereich von Intensitätsschwellwerten stabil bleiben — ideal für Texterkennung (wo Buchstaben blob-artig sind), Kennzeichen und Szenentext. Er handhabt ungleichmäßige Beleuchtung gut, weil jede Region bei ihrem eigenen Schwellwert erkannt wird. Ergebnisse nach Seitenverhältnis und Größe filtern, um offensichtliches Nicht-Text zu entfernen.
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)Feature-Matching
Brute-Force-Matching
Brute-Force-Matching probiert jedes Deskriptorenpaar — exakt, aber O(N*M). Für ORBs binäre Deskriptoren NORM_HAMMING; für SIFT/SURF-Float-Deskriptoren NORM_L2. crossCheck=True behält nur gegenseitig beste Matches (As bester ist B und umgekehrt) und entfernt viele Falschpositive. Jeder Match hat eine .distance — kleiner ist besser.
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)FLANN-Matching
FLANN (Fast Library for Approximate Nearest Neighbors) baut einen KD-Baum (für SIFT/SURF) oder LSH (für ORB), um approximative Matches zu finden — viel schneller als Brute-Force bei großen Deskriptormengen, auf Kosten gelegentlicher Verfehlungen. Die Parameter trees und checks tauschen Genauigkeit gegen Tempo. FLANN bei Tausenden Features; Brute-Force reicht für kleine Mengen.
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)KNN-Matching & Ratio-Test
Lowes Ratio-Test ist der Standardfilter fürs Feature-Matching: einen Match nur behalten, wenn der beste deutlich näher liegt als der zweitbeste (typischer Schwellwert 0.7-0.8). Die Intuition: Liegen beide Kandidaten ähnlich nah, ist der Match mehrdeutig und vermutlich falsch. Dieser eine Test entfernt die überwiegende Mehrheit der Falschpositiven.
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 mit RANSAC berechnet die perspektivische Transformation, die src auf dst mappt und Ausreißer ignoriert — die Inlier-Maske sagt dir, welche Matches zum Modell passen. Der Reprojektions-Schwellwert (5.0) ist in Pixeln; niedriger = strenger. Mindestens 4 gute Matches nötig. Damit ein bekanntes Objekt in einer Szene lokalisieren oder überlappende Fotos ausrichten.
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")Objektlokalisierung
Dies ist die klassische Objektlokalisierung-Pipeline: Features in beiden Bildern erkennen, matchen, mit RANSAC eine Homographie fitten, dann die Bounding-Box des Objekts in die Szene projizieren. Funktioniert für ebene Objekte oder weit entfernte 3D-Objekte (wo Perspektive dominiert). Sie scheitert an texturlosen, symmetrischen oder stark verdeckten Objekten — dafür Deep-Learning-Detektoren nutzen.
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)Gesichtserkennung
Haar-Cascade-Klassifikator
Haar-Cascades sind der klassische Viola-Jones-Detektor — schnell auf CPU und gut für Frontalgesichter, aber ungenauer als moderne Deep-Learning-Detektoren (MTCNN, SSD, RetinaFace). scaleFactor (>1) steuert die Mehrskalensuche — 1.1 = 10 % Skalenschritt; kleiner = langsamer, aber gründlicher. minNeighbors filtert überlappende Detektionen; erhöhen, um Falschpositive zu mindern.
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)Gesichter im Bild erkennen
Augen (oder Lächeln) innerhalb der Gesicht-ROI zu suchen ist der Standard-Effizienztrick: das ganze Bild nach Augen zu durchsuchen liefert viele Falschpositive, innerhalb einer bestätigten Gesicht-ROI sind sie selten. cv2.data.haarcascades zeigt auf das gebündelte XML-Verzeichnis — weitere Cascades (Auge, Lächeln, ganzer Körper, Kennzeichen) sind verfügbar. Die ROI VOR dem Cascade-Aufruf zuschneiden.
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)Gesichter im Video erkennen
Echtzeit-Gesichtserkennung per Webcam ist auf CPU machbar dank der Geschwindigkeit der Haar-Cascades. Der ROI-Blur-Trick (GaussianBlur nur auf der Gesichtsregion) ist eine einfache Datenschutz-/Anonymisierungstechnik. Um Gesichter über Frames zu tracken (Flackern vermeiden), Detektionen per IoU assoziieren und mit einem Kalman-Filter glätten — Cascades allein haben keine zeitliche Kontinuität.
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()Profil-/Seitengesicht
Haar-Cascades sind posenspezifisch — die Frontal-Cascade verpasst Seitengesichter, also mit der Profil-Cascade kombinieren. Da die Profil-Cascade auf einer Seite trainiert ist, die andere Seite erkennen, indem man das Bild horizontal kippt und die resultierenden Koordinaten spiegelt. Das verpasst weiterhin 3/4-Ansichten; moderne Detektoren (DNN, MTCNN) handhaben alle Posen in einem Modell.
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)DNN-Gesichtserkennung
OpenCVs dnn-Modul kann vortrainierte Caffe-/TensorFlow-/ONNX-Modelle ausführen — SSD- und ResNet-basierte Gesichtsdetektoren sind weit genauer als Haar-Cascades und handhaben alle Posen in einem Modell. blobFromImage erledigt Mittelwert-Subtraktion und Skalierung in einem Rutsch. Detektionen sind auf [0,1] normalisiert — mit (w, h, w, h) multiplizieren für Pixelboxen. Modelle: 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)Objekterkennung
HOG-Deskriptor
HOG (Histogram of Oriented Gradients) beschreibt lokale Form über Histogramme von Kantenrichtungen — kombiniert mit einem linearen SVM ist es ein klassischer Objektdetektor. Der vortrainierte Personen-Detektor funktioniert für Ganzkörper-Fußgänger in aufrechter Pose. winStride und scale tauschen Tempo gegen Trefferquote. Moderne Deep-Detektoren (YOLO, SSD) sind weit genauer, aber HOG läuft auf CPU ohne Modelldatei.
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)HOG-Feature-Visualisierung
Das Standard-HOG-Fenster ist 64x128 Pixel (die INRIA-Fußgängergröße). Parameter: window (64x128), block (16x16), block stride (8x8), cell (8x8), bins (9). Jeder Deskriptor ist 3780-D. Um eigene Objekte zu klassifizieren, HOG-Features für viele positive/negative Stichproben extrahieren und ein lineares SVM (scikit-learn) trainieren, dann den Detektor mit setSVMDetector setzen.
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 classifierTemplate-Matching
Template-Matching schiebt die Vorlage über das Bild und berechnet einen Ähnlichkeitswert — funktioniert nur bei exakten (oder fast exakten) Matches ohne Rotation oder Skalenwechsel. TM_CCOEFF_NORMED ist die robusteste Methode; Ergebnisse liegen in [-1, 1]. Für mehrere Matches die Antwortkarte schwellig machen und Nicht-Maximum-Unterdrückung anwenden, um überlappende Detektionen zu vermeiden.
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)Multi-Skalen-Template-Matching
Multi-Skalen-Template-Matching probiert bruteforceartig einen Bereich von Skalen — langsam, funktioniert aber, wenn die Größe der Vorlage im Bild unbekannt ist. Rotation kann es weiterhin nicht; dafür müsstest du auch über Winkel fahren (sehr langsam) oder Feature-Matching nutzen. Für Produktions-Objekterkennung einen trainierten Detektor (YOLO, SSD) statt Template-Matching verwenden.
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)DNN-Objekterkennung (YOLO)
OpenCVs dnn-Modul kann exportierte YOLO-/SSD-/Faster-RCNN-Gewichte ausführen — nützlich, wenn man kein volles DL-Framework installieren kann. YOLO-Ausgabe-Parsing ist ausführlich: jede Detektion hat Zentrum, Größe, Objectness und Klassen-Scores. Immer NMSBoxes (Nicht-Maximum-Unterdrückung) anwenden, um überlappende Boxen zu einer zu falten. Für Echtzeit YOLOv4-tiny oder auf ONNX + ein schnelleres Backend wechseln.
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 suppressionBildsegmentierung
K-Means-Clustering
K-means clustert Pixel nach Farbe — ein einfacher Weg, ein Bild zu posterisieren oder in K dominante Farben zu segmentieren. Float32-Pixel als (N, 3) übergeben (oder (N, 5), wenn du xy-Koordinaten für räumliches Clustering ergänzt). Höheres K liefert feinere Farbtrennung. Für räumliche Kohärenz jedes Pixel um seine (x, y)-Koordinaten ergänzen; für reine Farbquantisierung nur 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 ist ein interaktiver Vordergrund-Extraktor — du gibst ein umgebendes Rechteck und er modelliert Vordergrund/Hintergrund iterativ mit Gaußschen Mischverteilungen. Für feinere Ergebnisse mit GC_INIT_WITH_MASK verfeinern, nachdem du Pixel manuell gelabelt hast (sicherer VG / sicherer HG). Funktioniert gut für ein einzelnes hervorstechendes Objekt vor einem relativ einfachen Hintergrund.
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 behandelt das Bild als topografische Karte (Intensität = Höhe) und 'flutet' Becken von Saat-Markern aus — ohne gute Seeds erzeugt es schwere Übersegmentierung. Der Distanztransformation-Trick erzeugt sichere-Vordergrund-Seeds für sich berührende Objekte (z. B. überlappende Münzen). Marker: 0=unbekannt, 1=Hintergrund, 2..N=Objekte, -1=Grenze. Das ist die klassische 'berührende Objekte trennen'-Pipeline.
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 ist das Zauberstab-Werkzeug — von einem Seed-Pixel starten und alle verbundenen Pixel füllen, deren Farbe innerhalb von loDiff/upDiff entweder des Seeds (FIXED_RANGE) oder des vorherigen Pixels liegt. Die Maske muss 2 Pixel größer als das Bild sein (ein 1-Pixel-Rand auf jeder Seite). Nützlich für Region Growing, einfache Hintergrundersetzung und interaktive Auswahl.
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 1Connected Components
connectedComponents labelt jede weiße Region mit einer eindeutigen Ganzzahl — schneller als findContours, wenn du nur Anzahl, Fläche und Schwerpunkte brauchst. connectedComponentsWithStats liefert zusätzlich Bounding-Boxen und Flächen. Label 0 ist immer der Hintergrund. Die Standard-Konnektivität ist 8 (Diagonalen eingeschlossen); für strengere connectivity=4 übergeben. Für Partikelzählung und Blob-Analyse verwenden.
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 ist eine nichtparametrische Segmentierung, die Regionen ähnlicher Farbe 'glättet' und Kanten erhält — oft als Vorverarbeitung vor konturbasierter Segmentierung. sp (räumlicher Radius) steuert, wie weit der Algorithmus räumlich blickt; sr (Farbradius) die Farbtoleranz. Größere Werte erzeugen größere, glattere Regionen.
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)Kamerakalibrierung
Schachbrett-Kalibrierung
Die Kamerakalibrierung findet die intrinsische Matrix (Brennweite, Hauptpunkt) und Linsenverzerrungskoeffizienten aus Bildern eines bekannten Musters (Schachbrett ist Standard, weil Ecken leicht zu erkennen sind). Etwa 10-20 Bilder aus verschiedenen Winkeln nötig. cornerSubPix verfeinert Ecken auf Sub-Pixel-Genauigkeit — essenziell für eine gute Kalibrierung. Die an findChessboardCorners übergebene Mustergröße sind innere Ecken (Felder-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)Bild entzerren
undistort entfernt radiale und tangentiale Linsenverzerrung über die Kalibrierungsparameter. Für Video die Maps einmalig mit initUndistortRectifyMap vorberechnen und pro Frame remap anwenden — viel schneller als wiederholtes undistort. getOptimalNewCameraMatrix mit alpha=1 behält alle Pixel (mit schwarzen Rändern); alpha=0 beschneidet auf den gültigen Bereich.
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]Pose-Schätzung (ArUco)
ArUco-Marker sind quadratische Fiduzialmarker (wie QR-Codes) für die Pose-Schätzung — bei bekannter physischer Markergröße und Kamerakalibrierung bekommst du seine 3D-Rotation (rvec) und Translation (tvec) relativ zur Kamera. Verfügbar in opencv-contrib. drawFrameAxes zeichnet die lokalen X/Y/Z-Achsen des Markers — rot=X, grün=Y, blau=Z, Länge in Metern.
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)Fiduzial-Pose (solvePnP)
solvePnP (Perspective-n-Point) rekonstruiert die Kamerapose aus N 3D-zu-2D-Entsprechungen — mindestens 4 Punkte nötig. SOLVEPNP_ITERATIVE (Standard) für Genauigkeit oder SOLVEPNP_IPPE für ebene Ziele. Der rvec ist ein Rotationsvektor (Achse × Winkel); mit Rodrigues in eine 3x3-Matrix konvertieren. Das Fundament markerbasierter AR und 6-DOF-Tracking.
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)Reprojektionsfehler
Der Reprojektionsfehler ist der Goldstandard für Kalibrierungsqualität — er misst, wie weit projizierte 3D-Punkte von den erkannten 2D-Punkten landen. Eine gute Kalibrierung liegt unter 0,5 px im Mittel; über 1 px deutet meist auf einen schlechten Bildsatz, falsche Mustergröße oder Bewegungsunschärfe. Fehler pro Bild helfen, schlechte Kalibrierungsbilder zu finden und zu verwerfen.
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 cornerTiefe & Stereo
Stereo-Disparity-Map
StereoBM berechnet eine Disparity-Map (Pixel-Offset zwischen links/rechts) für ein entzerrtes Stereo-Paar — nähere Objekte haben größere Disparity. numDisparities muss ein Vielfaches von 16 sein; blockSize ungerade. Die Ausgabe ist int16, skaliert mit 16 (durch 16.0 teilen für Pixel-Disparity). StereoSGBM (semi-global block matching) ist langsamer, aber viel genauer.
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 erzwingt Glattheit über Scanzeilen hinweg (semi-global matching) — weit genauer als StereoBM bei ~5x Laufzeit. P1/P2 bestrafen Disparity-Änderungen von 1 bzw. >1; Faustregel ist P1=8*C*blockSize² und P2=32*C*blockSize², wobei C die Kanalzahl ist. Die speckle*-Parameter filtern kleine verrauschte Disparity-Regionen.
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)Stereo-Kalibrierung & -Rektifizierung
Stereo-Matching setzt voraus, dass die Bilder rektifiziert sind — Epipolarlinien horizontal ausgerichtet, sodass korrespondierende Punkte eine Zeile teilen. Die Pipeline: jede Kamera kalibrieren, stereo-kalibrieren, um R und T zwischen ihnen zu finden, stereoRectify für die Rektifizierungstransformationen, dann jeden Frame einmal remap. Nach der Rektifizierung ist die Disparity-Berechnung eine 1-D-Suche entlang der Zeilen.
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)Tiefe aus Disparity
Tiefe ist indirekt proportional zur Disparity: depth = focal × baseline / disparity. Basislinie (Kameraabstand) und Brennweite müssen in konsistenten Einheiten sein (typisch Pixel für Brennweite, Meter für Basislinie gibt Tiefe in Metern). Disparity ist verrauscht bei weit entfernten Objekten (kleine Disparity, großer Tiefenfehler) — deshalb brauchen Stereo-Kameras eine breite Basislinie für große Reichweite.
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)Optical Flow (Lucas-Kanade)
Lucas-Kanade berechnet sparsamen Optical Flow — er trackt eine Menge Keypoints über Frames, unter Annahme kleiner lokaler Bewegung. Schnell und genau bei mäßiger Bewegung; scheitert an großer oder schneller Bewegung (eine Pyramide nutzen, was calcOpticalFlowPyrLK bereits tut). status==1 heißt, der Punkt wurde erfolgreich getrackt. Für dichten Pixel-Flow calcOpticalFlowFarneback verwenden — viel langsamer, aber ein volles Bewegungsfeld.
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()Werkzeuge & Tipps
Performance-Messung
TickMeter ist der sauberste Weg, OpenCV-Aufrufe zu benchmarken — getTimeMilli liefert Wanduhr-Millisekunden. getTickCount/getTickFrequency geben zyklusgenaues Timing. Immer über viele Iterationen mitteln, um Jitter zu amortisieren, und cv2.imshow beim Benchmarken deaktivieren (GUI-Rendering dominiert). setNumThreads steuert das zugrunde liegende parallele Backend (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())Maus-Events
setMouseCallback registriert einen Handler für Maus-Events in einem benannten Fenster — nützlich für interaktive ROI-Auswahl, Annotation-Tools und einfache Mal-Apps. Übliche Events: LBUTTONDOWN, LBUTTONUP, MOUSEMOVE, RBUTTONDOWN. Der Handler muss eine Top-Level-(oder globale-)Funktion sein; Globals sind der Standardweg, State zu teilen, weil die Callback-Signatur fest ist.
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
Trackbars erlauben es, Parameter interaktiv zu tunen, ohne das Skript neu zu starten — unbezahlbar, um gute Schwellwerte, Kernelgrößen und HSV-Bereiche zu finden. Der Callback wird bei jeder Änderung aufgerufen (ein No-op reicht, wenn du getTrackbarPos in der Hauptschleife pollst). Trackbars müssen in einem benannten Fenster erzeugt und mit getTrackbarPos(window, name) gelesen werden.
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()ROI-Selector
selectROI öffnet ein interaktives Fenster, in dem der Nutzer ein Rechteck zieht und Enter/Leertaste drückt — viel einfacher als ein eigener Maus-Callback. 'c' drücken zum Abbrechen (liefert Nullen). selectROIs erlaubt mehrere Rechtecke nacheinander. Das zurückgegebene Tupel ist (x, y, w, h); zuschneiden mit 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()Häufige Fallstricke
Diese fünf Fallstricke verursachen die Mehrheit der OpenCV-Bugs: BGR/RGB-Verwechslung (rot und blau vertauscht), uint8-Überlauf (dunkle/helle Artefakte), Koordinatenreihenfolge (um eins verschobene ROIs), fehlende-Datei-None (Folgeoperationen crashen mit kryptischen Fehlern) und vergessen es waitKey (Fenster aktualisieren nicht). Früh verinnerlichen — jeder OpenCV-Entwickler trifft jeden davon mindestens einmal.
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 blankVerwandte OpenCV-Snippets
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?