Primeros pasos
Leer, mostrar y guardar imágenes
OpenCV lee las imágenes en orden BGR (no RGB) — una trampa común al interoperar con matplotlib o PIL. cv2.waitKey(0) bloquea hasta pulsar una tecla; llama siempre a destroyAllWindows() para cerrar las ventanas. La calidad JPEG es 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])Instalar e importar
opencv-python incluye solo los módulos principales; opencv-contrib-python añade módulos extra (a menudo con patentes) como SIFT/SURF y ArUco. Usa la variante headless en servidores/Docker para evitar arrastrar dependencias de X11. A pesar del nombre cv2, OpenCV 4.x sigue importándose como 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 npImagen como array de NumPy
Las imágenes de OpenCV son arrays de NumPy, así que lo que sabes de NumPy aplica igualmente. La convención de coordenadas es img[y, x] (fila, col) — lo opuesto a las coordenadas de imagen (x, y), una fuente frecuente de bugs. Las imágenes a color son (H, W, 3) en BGR; las de escala de grises son (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-299Acceso a píxeles y ROI
El acceso píxel a píxel vía img[y, x] es lento y desaconsejado en bucles — prefiere siempre el slicing de NumPy. Haz .copy() al asignar una ROI para que cambios posteriores en la fuente no se cuelen. Modificar img[:, :, canal] es la forma más rápida de operar sobre un solo canal de color.
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 channelTipos de datos y conversión
La mayoría de funciones de OpenCV esperan uint8 (0-255), pero algoritmos como SIFT, el flujo óptico y la detección de bordes a menudo necesitan float32. Nunca casteos directamente con .astype() tras restar — el desbordamiento de uint8 convierte -1 en 255. Usa cv2.absdiff o convierte a float primero. Vuelve siempre a uint8 antes de cv2.imwrite / imshow.
import cv2
import numpy as np
img = cv2.imread("photo.jpg") # uint8, 0-255
print(img.dtype, img.min(), img.max()) # uint8 0 255
# convert to float32 (0.0-1.0 for many algorithms)
f = img.astype(np.float32) / 255.0
# convert back to uint8 for display/save
u = (f * 255).astype(np.uint8)
# clamp then cast (avoid overflow when subtracting)
diff = cv2.absdiff(img, img) # safe subtraction
print(diff.dtype) # uint8
# CV_32F / CV_64F / CV_8U constants (used in some functions)
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
print(gray.dtype) # uint8Captura de vídeo
Abrir webcam
VideoCapture(0) abre la webcam por defecto; usa 1, 2... para cámaras adicionales. Llama siempre a cap.release() para liberar el dispositivo — olvidarlo puede dejar la cámara ocupada para otras apps. waitKey(1) espera ~1ms; el truco & 0xFF garantiza compatibilidad en sistemas de 64 bits donde waitKey devuelve más de 8 bits.
import cv2
cap = cv2.VideoCapture(0) # 0 = default camera
print(cap.isOpened()) # True if camera opened
while True:
ret, frame = cap.read() # ret is False at end of stream
if not ret:
break
gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)
cv2.imshow("frame", gray)
if cv2.waitKey(1) & 0xFF == ord('q'):
break
cap.release()
cv2.destroyAllWindows()Leer archivo de vídeo
CAP_PROP_FRAME_COUNT suele ser aproximado e poco fiable con algunos códecs — no dependas de él para búsquedas exactas. waitKey(int(1000/fps)) reproduce a una velocidad aproximadamente correcta; para tiempos precisos usa un reloj real. Algunos vídeos comprimidos no abren sin el backend adecuado (FFmpeg).
import cv2
cap = cv2.VideoCapture("movie.mp4")
# video properties
fps = cap.get(cv2.CAP_PROP_FPS)
width = cap.get(cv2.CAP_PROP_FRAME_WIDTH)
height = cap.get(cv2.CAP_PROP_FRAME_HEIGHT)
count = cap.get(cv2.CAP_PROP_FRAME_COUNT)
print(f"{width}x{height} @ {fps} fps, {count} frames")
while cap.isOpened():
ret, frame = cap.read()
if not ret:
break
cv2.imshow("video", frame)
if cv2.waitKey(int(1000 / fps)) & 0xFF == ord('q'):
break
cap.release()
cv2.destroyAllWindows()Guardar / escribir vídeo
El código FourCC depende de la plataforma y el códec: 'mp4v' es muy portable, 'XVID' produce .avi, 'avc1' da H.264 (puede no estar disponible sin códecs propietarios). El tamaño de fotograma pasado a VideoWriter DEBE coincidir con los fotogramas que escribas, o el archivo queda corrupto. Llama siempre a out.release() para vaciar y cerrar el archivo.
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()Ajustes de cámara
Las propiedades de cámara dependen del hardware y del driver — muchas webcams ignoran silenciosamente los ajustes no soportados o saltan al valor válido más cercano, así que lee de vuelta el valor real. CAP_PROP_EXPOSURE usa log2 de segundos (-4 = 1/16 s). La autoexposición debe deshabilitarse (fjar a 1) antes de que la exposición manual surta efecto en la mayoría de cámaras.
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 differTasa de fotogramas y tiempos
cap.get(CAP_PROP_FPS) devuelve el FPS configurado, no la tasa real de captura — mídelo con un reloj real. Una media móvil de 30 fotogramas suaviza el jitter. Los mayores asesinos de FPS son cv2.imshow (hilo de GUI) y cv2.imwrite por fotograma; para benchmarks, desactiva la visualización. Para tiempos deterministas, acumula fotogramas en un hilo y procésalos desde una cola.
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()Dibujo
Línea y rectángulo
Todas las funciones de dibujo mutan la imagen en el sitio — pasa una copia si quieres conservar la original. Las coordenadas son (x, y), opuestas a la indexación [y, x] de NumPy. Los colores son tuplas BGR. Usa thickness=-1 para formas rellenas y cv2.LINE_AA para líneas suaves (con anti-aliasing) en bordes diagonales.
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)Círculo y elipse
El parámetro axes de ellipse es (semiancho, semialto) — el ancho completo es 2 * axes[0]. angle rota toda la elipse; startAngle/endAngle dibujan arcos parciales (0° = derecha, en sentido antihorario). Dibujar arcos parciales es la forma estándar de renderizar porciones de gráfico de pastel o indicadores de dirección de movimiento.
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)Polígono y polilíneas
polylines acepta una lista de arrays de puntos, así que puedes dibujar varios polígonos en una sola llamada. El array de puntos debe ser int32 y reformarse a (-1, 1, 2). Usa fillPoly para formas rellenas; para rellenos translúcidos, dibuja sobre una capa superpuesta y mezcla con addWeighted. El flag isClosed conecta el último punto con el primero.
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)Texto
Las fuentes integradas de OpenCV son fuentes vectoriales Hershey — no soportan caracteres CJK/chinos. Para texto no latino, renderiza con PIL (Pillow) ImageFont y convierte de vuelta, o usa cv2.freetype de opencv-contrib. getTextSize devuelve ((ancho, alto), línea_base) — útil para centrar texto o dibujar una caja de fondo detrás.
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)Flecha y marcador
El tipLength de arrowedLine es una fracción de la longitud de la línea, así que las flechas más largas tienen puntas proporcionalmente mayores — fíjalo explícitamente si quieres tamaños de punta consistentes. drawMarker es cómodo para resaltar puntos clave (por ejemplo, características detectadas o esquinas); MARKER_TILTED_CROSS da un marcador en forma de X.
import cv2
import numpy as np
img = np.zeros((400, 400, 3), dtype=np.uint8)
# arrowedLine(img, pt1, pt2, color, thickness, tipLength)
cv2.arrowedLine(img, (50, 50), (350, 50), (0, 255, 0), 2, tipLength=0.05)
cv2.arrowedLine(img, (200, 200), (200, 380), (0, 0, 255), 3, tipLength=0.1)
# drawMarker (cross, tilted cross, circle, square, diamond)
cv2.drawMarker(img, (100, 300), (255, 0, 255),
markerType=cv2.MARKER_CROSS, markerSize=30, thickness=2)
cv2.drawMarker(img, (300, 300), (255, 255, 0),
markerType=cv2.MARKER_DIAMOND, markerSize=30, thickness=2)
cv2.imshow("img", img)
cv2.waitKey(0)Overlay y anotación
La técnica de overlay (dibujar sobre una copia y luego addWeighted) es la forma estándar de dibujar rellenos translúcidos — OpenCV no tiene alfa nativo para formas. Dibuja siempre el texto sólido DESPUÉS de mezclar para que se mantenga nítido; dibujar el texto sobre el overlay antes de mezclar lo vuelve borroso. Este patrón está en todas partes en la visualización de detección/segmentación.
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)Aritmética de imágenes
Sumar y restar
El cv2.add de OpenCV satura en 255 (250 + 10 = 255), mientras que el + de NumPy da la vuelta (250 + 10 = 8 por desbordamiento de uint8). Para imágenes, usa siempre cv2.add / cv2.subtract — el rebote crea artefactos visibles de negro/blanco. absdiff es el caballo de batalla para la sustracción de fondo y la detección de movimiento.
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)Mezcla y addWeighted
addWeighted exige que ambas imágenes tengan tamaño y dtype idénticos — redimensiona primero. El término gamma añade una constante a cada píxel, útil para controlar el brillo. El clásico fundido/disolución cruzada entre dos imágenes es simplemente addWeighted con alpha barriendo de 0 a 1.
import cv2
import numpy as np
a = cv2.imread("a.jpg")
b = cv2.imread("b.jpg")
b = cv2.resize(b, (a.shape[1], a.shape[0]))
# dst = alpha * a + beta * b + gamma
blend = cv2.addWeighted(a, 0.7, b, 0.3, 0)
# brighten by adding a constant (gamma)
bright = cv2.addWeighted(a, 1.0, a, 0.0, 50)
# fade between two images over N steps
for i in range(11):
alpha = i / 10.0
frame = cv2.addWeighted(a, alpha, b, 1 - alpha, 0)
cv2.imshow("fade", frame)
cv2.waitKey(200)Operaciones bit a bit
Las operaciones bit a bit son la forma estándar de aplicar una máscara: cv2.bitwise_or(src, dst, mask=mascara) copia src en dst solo donde la máscara es no cero. La máscara debe ser una imagen de un canal de 8 bits donde no cero significa 'conservar'. Es la fundación de la extracción de ROI y el reemplazo de fondo.
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)Diferencia de imagen y movimiento
La diferenciación de fotogramas es el detector de movimiento más simple: umbraliza la diferencia absoluta entre fotogramas consecutivos. Falla cuando la cámara se mueve e ignora el movimiento lento — para sistemas reales usa sustracción de fondo (cv2.createBackgroundSubtractorMOG2) o flujo óptico. La apertura morfológica quita el ruido; la dilatación fusiona manchas cercanas.
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 y enmascarado
bitwise_and con una máscara es la forma idiomática de extraer regiones irregulares. La indexación booleana de NumPy (img[mascara]) es más flexible pero devuelve un array plano de píxeles, no una imagen con forma. Haz siempre .copy() de las ROIs que planees reutilizar — el slicing devuelve una vista que es alias del original.
import cv2
import numpy as np
img = cv2.imread("photo.jpg")
h, w = img.shape[:2]
# build a mask: white circle on black background
mask = np.zeros((h, w), dtype=np.uint8)
cv2.circle(mask, (w // 2, h // 2), 150, 255, -1)
# keep only the masked region, zero elsewhere
masked = cv2.bitwise_and(img, img, mask=mask)
# extract ROI by bounding box
roi = img[100:300, 200:500].copy()
# put ROI back (or to a different location)
img[0:200, 0:300] = roi
# boolean mask (NumPy) — also works, but converts to 0/255
bool_mask = np.zeros((h, w), dtype=bool)
bool_mask[100:300, 200:500] = True
img_masked = img.copy()
img_masked[~bool_mask] = 0Saturación vs rebote
La trampa del desbordamiento de uint8: NumPy rebota (300 -> 44), OpenCV satura (300 -> 255). Para cualquier aritmética que pueda exceder 0-255, o usa cv2.add/subtract o promociona primero a int16/float32 y recorta de vuelta. Mezclar operaciones de cv2 y NumPy en el mismo pipeline es la fuente número 1 de misteriosos artefactos de píxeles oscuros/brillantes.
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 -> 44Transformaciones geométricas
Redimensionar / escalar
INTER_AREA es lo mejor para reducir (evita el aliasing), INTER_CUBIC o INTER_LINEAR para ampliar. INTER_NEAREST es el más rápido pero en bloques — se usa para imágenes de etiquetas/máscaras donde no debes introducir valores de píxel nuevos. La tupla dsize es (ancho, alto), lo opuesto a img.shape que es (alto, ancho).
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) # enlargingRotación
cv2.rotate es mucho más rápido que warpAffine para múltiplos de 90°. El ángulo de getRotationMatrix2D va en grados, positivo = antihorario. Para rotar sin recortar, recalcula la caja envolvente (new_w, new_h) y desplaza la matriz de rotación — de lo contrario las esquinas de una imagen grande rotada se cortan.
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))Transformación afín
Una transformación afín conserva el paralelismo y las proporciones de distancias — se define con 3 correspondencias de puntos (6 grados de libertad). warpAffine usa mapeo directo implícitamente vía búsqueda inversa, así que M mapea src->dst pero la función lo invierte internamente. Usa borderMode=BORDER_REFLECT o BORDER_CONSTANT para controlar cómo se rellenan las regiones fuera de límites.
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)Transformación de perspectiva
La perspectiva (homografía) se define con 4 pares de puntos no colineales — 8 GLD. Esta es la transformación estándar del 'escáner de documentos': elige las 4 esquinas de una tarjeta/papel en la foto y deforma a un rectángulo. getPerspectiveTransform necesita exactamente 4 puntos; para un ajuste sobredeterminado usa cv2.findHomography con RANSAC.
import cv2
import numpy as np
img = cv2.imread("card.jpg")
h, w = img.shape[:2]
# 4 point correspondences define a perspective (homography)
src = np.float32([[73, 110], [320, 78], [380, 350], [40, 320]])
dst = np.float32([[0, 0], [w, 0], [w, h], [0, h]])
M = cv2.getPerspectiveTransform(src, dst)
warped = cv2.warpPerspective(img, M, (w, h))
# invert the homography to map back
M_inv = cv2.getPerspectiveTransform(dst, src)
restored = cv2.warpPerspective(warped, M_inv, (w, h))Voltear y reflejar
flip es una operación barata en memoria — mucho más rápida que warpAffine. Convención de signo de flipCode: positivo voltea horizontalmente, 0 verticalmente, negativo ambos. cv2.transpose intercambia ejes y a veces se usa como una rotación rápida de 90° combinada con un flip.
import cv2
img = cv2.imread("photo.jpg")
# flip(img, flipCode)
# 0 -> vertical flip (around x-axis) (upside-down)
# 1 -> horizontal flip (around y-axis) (mirror)
# -1 -> both (180° rotation equivalent)
v = cv2.flip(img, 0)
h = cv2.flip(img, 1)
both = cv2.flip(img, -1)
# transpose (swap x and y axes) — like a 90° rotation + flip
t = cv2.transpose(img)Remap (mapeo personalizado)
remap es la transformación geométrica más general — resize, rotar e incluso la corrección de distorsión de barril/lente se expresan como remap. Construye siempre los mapas con vectorización de NumPy, no con bucles de Python (la versión con bucle de arriba es solo ilustrativa — es ~100 veces más lenta). INTER_LINEAR es el valor por defecto; para precisión subpíxel en bordes usa 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)Filtrado de imágenes
Desenfoque promedio (box filter)
El desenfoque promedio es el filtro de paso bajo más simple — reemplaza cada píxel por la media de su vecindario. Los kernels deben ser impares y positivos. Kernels mayores desenfocan más pero también destruyen el detalle más rápido. Úsalo cuando quieras específicamente una ponderación uniforme; para imágenes naturales el desenfoque gaussiano es casi siempre mejor elección.
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)Desenfoque gaussiano
El desenfoque gaussiano es el kernel de suavizado por defecto — pondera a los vecinos por una gaussiana, conservando mejor los bordes que un box filter. Si pasas ksize=(0,0) y sigmaX, OpenCV computa automáticamente el tamaño del kernel. El desenfoque gaussiano es un paso previo exigido antes de Canny, el submuestreo y el Laplaciano para suprimir la amplificación de ruido.
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)Desenfoque mediana
El desenfoque mediana es el filtro de referencia para el ruido de sal y pimienta (impulso) — reemplaza cada píxel por la mediana de su vecindario, así que los atípicos aislados se eliminan en lugar de extenderse. A diferencia del gaussiano, preserva bien los bordes. El tamaño del kernel debe ser impar. Es más lento que el gaussiano/box porque implica ordenación.
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)Filtro bilateral
El filtrado bilateral suaviza las regiones planas manteniendo los bordes afilados — es un filtro no lineal que preserva bordes y pondera a los vecinos por proximidad espacial Y similaridad de color. Es mucho más lento que el gaussiano (a menudo 10 veces). La aplicación repetida es el clásico paso previo de 'caricaturización'; los valores grandes de sigmaColor mezclan a través de más colores.
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)Nitidez (kernel)
Los kernels de nitidez enfatizan las altas frecuencias — pero también amplifican el ruido, así que aplícalos tras eliminar el ruido. El clásico kernel de nitidez 3x3 suma 1 (conserva el brillo); una suma > 1 aclara. La técnica de máscara de enfoque (restar una copia desenfocada) es más controlable y es la que realmente usan la mayoría de editores de fotos.
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)Kernel personalizado (filter2D)
filter2D aplica un kernel de correlación arbitrario — ddepth=-1 conserva la profundidad de la fuente. Los kernels pueden ser float para coeficientes negativos; si el resultado se vuelve negativo, cambia a ddepth=cv2.CV_16S o CV_32F y luego convertScaleAbs de vuelta. Los kernels separables (producto externo de kernels 1D) son mucho más rápidos vía sepFilter2D.
import cv2
import numpy as np
img = cv2.imread("photo.jpg")
# emboss kernel
emboss = np.array([[-2, -1, 0],
[-1, 1, 1],
[ 0, 1, 2]], dtype=np.float32)
out = cv2.filter2D(img, -1, emboss)
# edge enhance (Laplacian-like)
edge = np.array([[ 0, 1, 0],
[ 1, -4, 1],
[ 0, 1, 0]], dtype=np.float32)
edges = cv2.filter2D(img, -1, edge)
# box blur done manually
box = np.ones((5, 5), dtype=np.float32) / 25.0
blurred = cv2.filter2D(img, -1, box)
# separable filter (Gaussian) — faster than 2D
kx = cv2.getGaussianKernel(5, 1.0) # 5x1
ky = cv2.getGaussianKernel(5, 1.0) # 5x1
g2d = kx @ ky.T # 5x5
out2 = cv2.filter2D(img, -1, g2d)Operaciones morfológicas
Erosión y dilatación
La erosión encoge las regiones de primer plano (blanco) y quita las motas de ruido pequeñas; la dilatación las agranda y rellena huecos pequeños. La forma del kernel importa: RECT para uso general, ELLIPSE para características más redondeadas, CROSS para afinar/conectar a lo largo de los ejes. iterations=N repite la operación N veces, equivalente a usar un kernel mayor.
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))Apertura y cierre
La apertura (erosionar→dilatar) elimina pequeñas motas brillantes sin cambiar el tamaño de los objetos mayores. El cierre (dilatar→erosionar) rellena pequeños huecos oscuros. Son idempotentes — aplicar dos veces es lo mismo que una vez. El patrón clásico de eliminación de ruido es cerrar-luego-abrir (o abrir-luego-cerrar) para manejar ambos tipos de defectos.
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)Gradiente morfológico
El gradiente morfológico (dilatación - erosión) produce un contorno grueso de los límites de los objetos — útil como detector de bordes rápido o como máscara para segmentar. A diferencia de Canny da bordes anchos y rellenos, así que sirve para resaltar regiones más que para medir posiciones exactas de bordes.
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 y black hat
Top-hat extrae estructuras brillantes pequeñas menores que el kernel (por ejemplo, texto sobre un documento oscuro); black-hat extrae estructuras oscuras pequeñas. Juntos se usan para la extracción de sombra/resaltado y como corrector rápido de iluminación desigual (el truco de dividir por el fondo es común en escáneres de documentos).
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)Esqueletización
La esqueletización morfológica adelgaza una forma binaria a un eje medial de 1 píxel de ancho — útil para OCR, huellas dactilares y análisis de vasos. El bucle iterativo de erosionar-restar-abrir corre hasta que la imagen queda vacía. Para uso en producción, el medial_axis o thinning de scikit-image son más rápidos y dan resultados más limpios.
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 es el emparejador de patrones morfológico — encuentra configuraciones exactas de píxeles de primer plano y fondo, útil para detectar formas concretas como esquinas o cruces en T. El kernel usa 1 para primer plano requerido, -1 para fondo requerido, 0 para no importa. Es de nicho pero imbatible para localizar patrones exactos.
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")Detección de bordes
Detector de bordes Canny
Canny es el detector de bordes más usado: suavizado gaussiano → gradientes Sobel → supresión de no máximos → histéresis (dos umbrales). Los píxeles por encima del umbral alto son bordes; los que están entre bajo y alto son bordes solo si están conectados a un borde fuerte. El truco de auto-umbral (mediana × 0.7/1.3) funciona bien con imágenes variadas.
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)Operador Sobel
Sobel computa la primera derivada — usa ddepth=cv2.CV_64F (o CV_16S) para capturar gradientes negativos, de lo contrario el desbordamiento de uint8 vuelve invisibles las transiciones de oscuro a brillante. ksize=3 es el estándar; ksize=5 da bordes más suaves pero más anchos. La magnitud (sqrt(sx²+sy²)) es la base de Canny y de muchos detectores de características.
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)Laplaciano
El Laplaciano es la segunda derivada — es muy sensible al ruido, así que desenfoca siempre primero. Detecta pasos por cero (cambios de signo), dando bordes finos y precisos pero sin dirección. Se usa más a menudo en la detección de bordes de Marr-Hildreth y como entrada del canal 'L' en el afilado de imágenes (máscara de enfoque). Usa CV_64F porque la segunda derivada se balancea duramente hacia lo negativo.
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)Filtro Scharr
Scharr es una variante de Sobel diseñada para ventanas 3x3 — cuando debas usar un kernel pequeño, da una dirección de gradiente más precisa que Sobel ksize=3. Para kernels mayores (5x5, 7x7) Sobel está bien. cv2.Sobel con ksize=-1 equivale a Scharr. Scharr es preferido cuando la dirección del gradiente importa (HOG, orientación de bordes).
import cv2
import numpy as np
img = cv2.imread("photo.jpg", cv2.IMREAD_GRAYSCALE)
# Scharr: a Sobel variant optimized for 3x3 kernels
# better rotational symmetry than 3x3 Sobel
sx = cv2.Scharr(img, cv2.CV_64F, 1, 0)
sy = cv2.Scharr(img, cv2.CV_64F, 0, 1)
mag = cv2.magnitude(sx, sy)
mag_u8 = cv2.convertScaleAbs(mag)
# equivalent to Sobel with ksize=-1
sx2 = cv2.Sobel(img, cv2.CV_64F, 1, 0, ksize=-1)Pipeline de detección de bordes
El pipeline escala de grises → eliminar ruido → Canny → dilatar → findContours cubre una enorme fracción de las tareas prácticas de bordes. La dilatación antes de hallar contornos cierra los bordes rotos que de otro modo partirían un objeto en muchos. Ajustar los umbrales de Canny y el tamaño del kernel de eliminación de ruido es donde va la mayor parte del esfuerzo de ingeniería.
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)Contornos
Hallar contornos
findContours muta la imagen fuente en OpenCV 3.x — pasa una copia si necesitas el binario después. RETR_EXTERNAL devuelve solo los contornos más externos (lo más rápido); RETR_TREE da la jerarquía completa para formas anidadas (huecos dentro de objetos). CHAIN_APPROX_SIMPLE descarta los puntos redundantes a lo largo de líneas rectas, ahorrando memoria.
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)Dibujar contornos
drawContours(imagen, contornos, contourIdx, color, grosor): contourIdx=-1 los dibuja por completo; un índice concreto dibuja uno. Thickness=-1 rellena el contorno. Dibujar sobre una imagen en blanco es la forma estándar de construir una máscara de contorno para operaciones posteriores como el color medio o un histograma enmascarado.
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)Propiedades de contornos
contourArea está en píxeles e ignora cualquier hueco (usa el contorno con la jerarquía RETR_CCOMP para el área neta). El diccionario de momentos da el centroide (m10/m00, m01/m00) — protégete contra la división por cero si m00 es 0 (contornos degenerados). La relación de aspecto y la extensión son los descriptores de forma más simples para clasificar formas.
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}")Rectángulos envolventes
boundingRect da una caja alineada a los ejes (rápida, simple); minAreaRect da el rectángulo rotado más pequeño (útil para medir la orientación/tamaño real de un objeto). boxPoints convierte el rectángulo rotado a 4 puntos de esquina que puedes pasar a drawContours. minEnclosingCircle es el círculo más pequeño que contiene el contorno.
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)Aproximación de contornos
approxPolyDP simplifica un contorno a un polígono con menos vértices usando el algoritmo de Douglas-Peucker. El epsilon (típicamente 1-5% del perímetro) controla la tolerancia: menor conserva más detalle. Contar vértices es el clasificador de formas manual clásico — triángulos=3, rectángulos=4, círculos=muchos.
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)Envolvente convexa y defectos
La envolvente convexa es la forma convexa más pequeña que encierra al contorno — útil para medir la compacidad de un objeto y para la detección de manos/dedos vía defectos de convexidad. La profundidad de cada defecto mide cuánto se 'hunde' el contorno respecto a la envolvente; los defectos profundos en una silueta de mano corresponden típicamente a los huecos entre dedos.
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)Umbralización
Umbral básico
THRESH_BINARY: arriba->255, abajo->0. THRESH_TRUNC: arriba->acotado en thresh, abajo->sin cambios. THRESH_TOZERO: arriba->sin cambios, abajo->0. El ret devuelto iguala al umbral de entrada para la umbralización simple pero se vuelve significativo para Otsu/Triangle. Elige el tipo según cómo quieras que se manejen los píxeles fuera de rango.
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)Umbral adaptativo
La umbralización adaptativa computa un umbral distinto por píxel según su vecindario local — esencial para imágenes con iluminación desigual (por ejemplo, fotografías de documentos). blockSize debe ser impar (típicamente 11-31) y mayor que el tamaño de la característica. C resta una constante a la media local; súbela para suprimir el ruido de bajo contraste.
import cv2
img = cv2.imread("doc.png", cv2.IMREAD_GRAYSCALE)
img = cv2.medianBlur(img, 5)
# adaptiveThreshold(src, maxValue, adaptiveMethod, thresholdType, blockSize, C)
# adaptiveMethod:
# ADAPTIVE_THRESH_MEAN_C -> mean of neighborhood minus C
# ADAPTIVE_THRESH_GAUSSIAN_C -> weighted mean minus C
adap_mean = cv2.adaptiveThreshold(img, 255,
cv2.ADAPTIVE_THRESH_MEAN_C, cv2.THRESH_BINARY, 11, 2)
adap_gauss = cv2.adaptiveThreshold(img, 255,
cv2.ADAPTIVE_THRESH_GAUSSIAN_C, cv2.THRESH_BINARY, 11, 2)Umbralización de Otsu
La técnica de Otsu halla el umbral global óptimo maximizando la varianza entre las clases de primer plano y fondo — pasa thresh=0 y añade el flag THRESH_OTSU. Desenfoca siempre primero; Otsu es sensible al ruido del histograma. La técnica Triangle funciona mejor en imágenes con un único pico dominante (por ejemplo, microscopía). El ret devuelto es el umbral computado.
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}")Umbral por color (inRange)
inRange es la herramienta estándar de segmentación por color — convierte a HSV primero porque separa el color (tono) del brillo, haciendo los umbrales robustos a cambios de iluminación. El tono del rojo envuelve en 0/180, así que necesitas dos máscaras unidas con OR. Desenfoca siempre antes de inRange para reducir las motas de ruido en la máscara.
import cv2
import numpy as np
img = cv2.imread("photo.jpg")
hsv = cv2.cvtColor(img, cv2.COLOR_BGR2HSV)
# detect a range of green pixels
lower = np.array([35, 50, 50])
upper = np.array([85, 255, 255])
mask = cv2.inRange(hsv, lower, upper)
# apply mask to the original
result = cv2.bitwise_and(img, img, mask=mask)
# hue wraps around for red (0-10 and 170-180)
mask1 = cv2.inRange(hsv, np.array([0, 50, 50]), np.array([10, 255, 255]))
mask2 = cv2.inRange(hsv, np.array([170, 50, 50]), np.array([180, 255, 255]))
red_mask = cv2.bitwise_or(mask1, mask2)Pipeline de umbralización
El pipeline quitar ruido → umbralizar → morfología maneja la mayoría de tareas de binarización. Elige Otsu para iluminación uniforme, adaptativo para desigual. El cierre-luego-apertura morfológico elimina tanto los huecos interiores como las motas exteriores. Inspecciona siempre la máscara binaria — los parámetros de umbral son casi siempre específicos de la imagen y necesitan ajuste por dataset.
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)Binarización para OCR
Para OCR, el gaussiano adaptativo casi siempre supera al Otsu global en documentos fotografiados por la iluminación desigual. Iguala blockSize a la altura del carácter (regla práctica: 1-2× el ancho del trazo × 4). La mayoría de motores OCR (Tesseract) prefieren texto negro sobre fondo blanco — invierte si tu binario es al revés.
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)Espacios de color
BGR / RGB / gris
OpenCV lee las imágenes como BGR por defecto; la mayoría de las demás librerías (matplotlib, PIL, scikit-image) usan RGB. Olvidar cvtColor es la causa más común de imágenes con 'rojo y azul intercambiados'. La conversión a escala de grises usa pesos perceptuales (Y = 0.299R + 0.587G + 0.114B), no un promedio simple.
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 a HSV
El HSV de OpenCV usa H en 0-179 (no 0-360) para que quepa en uint8 — una fuente frecuente de bugs de factor 2 al portar código de otras librerías. S y V son 0-255. HSV es el espacio de referencia para la segmentación por color porque el tono es aproximadamente invariante a los cambios de brillo — úsalo para seguir objetos por color.
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 a LAB
CIELAB aproxima la percepción humana — cambios numéricos iguales se ven aproximadamente igual de distintos, razón por la que se usa para métricas de diferencia de color (ΔE). El canal L codifica solo la luminosidad, así que editar L es la forma más limpia de aclarar una imagen sin desplazar colores. El LAB de OpenCV usa 0-255 para cada canal, no el estándar 0-100 para 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)Seguimiento por color (HSV)
El seguimiento por color basado en HSV es el seguidor de objetos más simple — elige el rango de tono, umbraliza, halla la mancha mayor. Falla con mala iluminación (baja saturación), con objetos de fondo de color similar y en superficies reflectantes. Para un seguimiento robusto combínalo con camshift/meanshift (usa retroproyección de un histograma de tono) o un filtro de Kalman para suavizar el movimiento.
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()Separar y fusionar canales
split/merge son cómodos pero más lentos que la indexación de NumPy — img[:, :, 0] es el canal azul y modificarlo es más rápido que split. Pasa siempre los canales a merge en el orden correcto para tu espacio de color objetivo. El truco de 'poner a cero dos canales' es la forma clásica de visualizar la contribución de un solo canal de color.
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])Otros espacios de color
YCrCb separa la luminancia (Y) de la crominancia (Cr, Cb) — la base de la compresión JPEG y MPEG, que descarta el detalle de crominancia porque los humanos son menos sensibles al color que al brillo. HLS difiere de HSV en que el blanco está en L=1 sin importar la saturación, haciendo a HLS mejor para algunos efectos de sombreado. Elige el espacio que haga tu operación invariante a lo que no te importa.
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)Histogramas
Calcular histograma
calcHist toma una lista de imágenes, una lista de canales, una máscara opcional (None = imagen entera), el conteo de bins y el rango de valores. Para histogramas multidimensionales (por ejemplo, 2D tono-saturación) pasa dos canales y dos tamaños de bin — usado en la retroproyección de histograma para el seguimiento por color. El histograma de cada canal se computa independientemente.
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])Graficar histograma
Matplotlib es la forma más fácil de visualizar histogramas — pero recuerda convertir BGR a RGB para los colores de la leyenda, o los colores de tu gráfico no coincidirán con las etiquetas de los canales. Un histograma sesgado a la izquierda es una imagen oscura, a la derecha clara; un pico estrecho significa bajo contraste. Úsalo para diagnosticar problemas de exposición y balance de blancos.
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()Ecualización de histograma
La ecualización de histograma estira las intensidades de los píxeles para aprovechar el rango 0-255 completo — genial para imágenes de bajo contraste pero puede quemar los resaltados y amplificar el ruido. NUNCA ecualices los tres canales BGR directamente — desplaza los colores. Convierte siempre a un espacio de luminancia/crominancia (YCrCb, LAB, HSV), ecualiza la luminancia y convierte de vuelta.
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 (ecualización adaptativa)
CLAHE es la alternativa de calidad de producción a la ecualización global — opera sobre pequeñas teselas así que funciona en imágenes con iluminación desigual, y clipLimit acota la amplificación de contraste para no explotar el ruido. Un tileGridSize de 8x8 es el valor por defecto; teselas menores dan más adaptación local. La elección de referencia para imagen médica y mejora de documentos.
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)Retroproyección de histograma
La retroproyección de histograma responde '¿dónde se parecen los píxeles a la distribución de color de mi ROI?'. Construye un histograma 2D de tono-saturación a partir de una muestra, luego retroproyéctalo sobre una imagen objetivo para obtener un mapa de probabilidad. Es la base del seguimiento meanShift/camShift — mucho más robusto que un rango HSV fijo porque aprende la distribución de color real del objetivo.
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)Detección de características
Detector de esquinas Harris
Harris detecta esquinas comprobando si mover una pequeña ventana en cualquier dirección causa un gran cambio de intensidad — las esquinas cambian en todas las direcciones, los bordes en una, las regiones planas en ninguna. La salida es un mapa de respuesta de esquinas; umbraliza respecto al máximo (por ejemplo, 0.01 * max). blockSize es el vecindario para la computación del tensor de estructura.
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 mejora a Harris usando min(valor_propio1, valor_propio2) como puntuación, lo que da esquinas más estables para el seguimiento. maxCorners acota el conteo; qualityLevel es una fracción de la respuesta de esquina más fuerte (0.01 = 1% de la mejor); minDistance impone separación espacial entre esquinas detectadas. Es la entrada por defecto del seguidor de flujo óptico de Lucas-Kanade.
import cv2
import numpy as np
img = cv2.imread("photo.jpg")
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
# goodFeaturesToTrack returns the N strongest corners
corners = cv2.goodFeaturesToTrack(gray, maxCorners=100,
qualityLevel=0.01,
minDistance=10)
corners = np.int0(corners)
for c in corners:
x, y = c.ravel()
cv2.circle(img, (x, y), 3, (0, 0, 255), -1)SIFT (características invariantes a escala)
SIFT halla puntos clave invariantes a escala y rotación y un descriptor de 128D para cada uno — robusto a iluminación, punto de vista y oclusión parcial. Estuvo patentado durante años y se volvió libre en OpenCV 4.4. Usa SIFT para emparejamiento de alta exactitud donde la velocidad sea secundaria. DRAW_RICH_KEYPOINTS dibuja la escala y orientación de cada punto clave.
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 combina el detector de puntos clave FAST con el descriptor BRIEF — ambos libres de patentes y ~10 veces más rápido que SIFT, haciendo de ORB la elección estándar para emparejamiento en tiempo real en móvil/embebido. Los descriptores son binarios (32 bytes frente a los 128 floats de SIFT), así que el emparejamiento usa distancia de Hamming. Ligeramente menos robusto que SIFT a escala/rotación, pero excelente por el coste.
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)Detector FAST
FAST comprueba si un círculo de 16 píxeles alrededor de un candidato tiene N píxeles contiguos, cada uno más brillante o más oscuro que el centro — extremadamente rápido porque cortocircuita. Devuelve solo puntos clave, sin descriptores (usa BRIEF u ORB para descriptores). Un umbral menor = más (y más ruidosas) esquinas; la supresión de no máximos elimina duplicados en los máximos locales.
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 (regiones extremas máximamente estables)
MSER halla regiones que se mantienen estables a lo largo de un rango de umbrales de intensidad — ideal para detección de texto (donde las letras son tipo mancha), matrículas y texto de escena. Maneja bien la iluminación desigual porque cada región se detecta en su propio umbral. Filtra los resultados por relación de aspecto y tamaño para quitar lo que obviamente no es texto.
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)Emparejamiento de características
Emparejamiento de fuerza bruta
El emparejamiento de fuerza bruta prueba cada par de descriptores — exacto pero O(N*M). Para los descriptores binarios de ORB usa NORM_HAMMING; para los descriptores float de SIFT/SURF usa NORM_L2. crossCheck=True conserva solo los mejores emparejamientos mutuos (el mejor de A es B y viceversa), lo que elimina muchos falsos positivos. Cada emparejamiento tiene un .distance — menor es mejor.
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)Emparejamiento FLANN
FLANN (Fast Library for Approximate Nearest Neighbors) construye un KD-tree (para SIFT/SURF) o LSH (para ORB) para hallar emparejamientos aproximados — mucho m ás rápido que la fuerza bruta en grandes conjuntos de descriptores al coste de fallos ocasionales. Los parámetros trees y checks intercambian exactitud por velocidad. Usa FLANN cuando tengas miles de características; la fuerza bruta está bien para conjuntos pequeños.
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)Emparejamiento KNN y test de ratio
El test de ratio de Lowe es el filtro estándar del emparejamiento de características: conserva un emparejamiento solo si el mejor es significativamente más cercano que el segundo mejor (umbral típico 0.7-0.8). La intuición: si ambos candidatos están igual de cerca, el emparejamiento es ambiguo y probablemente erróneo. Este único test elimina la gran mayoría de falsos positivos.
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)Homografía (RANSAC)
findHomography con RANSAC computa la transformación de perspectiva que mapea src a dst ignorando los atípicos — la máscara de interiores te dice qué emparejamientos concuerdan con el modelo. El umbral de reproyección (5.0) va en píxeles; menor = más estricto. Necesitas al menos 4 buenos emparejamientos. Úsalo para localizar un objeto conocido en una escena o alinear fotos solapadas.
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")Localización de objetos
Este es el pipeline clásico de localización de objetos: detecta características en ambas imágenes, emparéjalas, ajusta una homografía con RANSAC y luego proyecta la caja envolvente del objeto a la escena. Funciona para objetos planos u objetos 3D lejanos (donde domina la perspectiva). Falla en objetos sin textura, simétricos u muy ocluidos — para esos usa detectores de deep learning.
import cv2
import numpy as np
img1 = cv2.imread("box.png", cv2.IMREAD_GRAYSCALE)
img2 = cv2.imread("scene.png", cv2.IMREAD_GRAYSCALE)
sift = cv2.SIFT_create()
kp1, des1 = sift.detectAndCompute(img1, None)
kp2, des2 = sift.detectAndCompute(img2, None)
bf = cv2.BFMatcher(cv2.NORM_L2)
good = [m for m, n in bf.knnMatch(des1, des2, k=2)
if m.distance < 0.75 * n.distance]
src = np.float32([kp1[m.queryIdx].pt for m in good]).reshape(-1, 1, 2)
dst = np.float32([kp2[m.trainIdx].pt for m in good]).reshape(-1, 1, 2)
H, _ = cv2.findHomography(src, dst, cv2.RANSAC, 5.0)
# project the object's corners into the scene
h, w = img1.shape
corners = np.float32([[0, 0], [w-1, 0], [w-1, h-1], [0, h-1]]).reshape(-1, 1, 2)
scene_corners = cv2.perspectiveTransform(corners, H)
out = cv2.cvtColor(img2, cv2.COLOR_GRAY2BGR)
cv2.polylines(out, [np.int32(scene_corners)], True, (0, 255, 0), 3)Detección de rostros
Clasificador Haar cascade
Las cascadas Haar son el detector clásico de Viola-Jones — rápido en CPU y bueno para rostros frontales, pero menos preciso que los detectores modernos de deep learning (MTCNN, SSD, RetinaFace). scaleFactor (>1) controla la búsqueda multiescala — 1.1 = paso de escala del 10%; menor = más lento pero más minucioso. minNeighbors filtra detecciones solapadas; súbelo para reducir falsos positivos.
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)Detectar rostros en imagen
Detectar ojos (o sonrisa) dentro de la ROI del rostro es el truco estándar de eficiencia: buscar ojos en toda la imagen da muchos falsos positivos, pero dentro de una ROI de rostro confirmada son raros. cv2.data.haarcascades apunta al directorio XML incluido — hay disponibles otras cascadas (ojo, sonrisa, cuerpo entero, matrícula). Recorta la ROI ANTES de llamar a la cascada.
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)Detectar rostros en vídeo
La detección de rostros en tiempo real con webcam es factible en CPU gracias a la velocidad de las cascadas Haar. El truco de desenfoque de ROI (GaussianBlur solo sobre la región del rostro) es una técnica simple de privacidad/anonimización. Para seguir rostros entre fotogramas (evitar parpadeo), asocia detecciones por IoU y suaviza con un filtro de Kalman — las cascadas por sí solas no tienen continuidad temporal.
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()Rostro de perfil / lateral
Las cascadas Haar son específicas de pose — la cascada frontal pierde los rostros laterales, así que combínala con la de perfil. Como la cascada de perfil se entrenó con un lado, detecta el otro lado volteando la imagen horizontalmente y reflejando las coordenadas resultantes. Esto aún pierde las vistas de 3/4; los detectores modernos (DNN, MTCNN) manejan todas las poses en un solo modelo.
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)Detección de rostros con DNN
El módulo dnn de OpenCV puede correr modelos preentrenados de Caffe/TensorFlow/ONNX — los detectores de rostros basados en SSD y ResNet son mucho más precisos que las cascadas Haar y manejan todas las poses en un solo modelo. blobFromImage hace la resta de media y el escalado de una vez. Las detecciones están normalizadas [0,1] — multiplica por (w, h, w, h) para obtener cajas en píxeles. Modelos: SSD (Caffe), YuNet (ONNX, vía 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)Detección de objetos
Descriptor HOG
HOG (Histograma de Gradientes Orientados) describe la forma local vía histogramas de direcciones de bordes — combinado con una SVM lineal es un detector de objetos clásico. El detector de personas preentrenado funciona para peatones de cuerpo entero en poses erguidas. winStride y scale intercambian velocidad por recall. Los detectores profundos modernos (YOLO, SSD) son mucho más precisos pero HOG corre en CPU sin archivo de modelo.
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)Visualización de características HOG
La ventana HOG estándar es de 64x128 píxeles (el tamaño peatón de INRIA). Parámetros: ventana (64x128), bloque (16x16), paso de bloque (8x8), celda (8x8), bins (9). Cada descriptor es de 3780D. Para clasificar objetos personalizados, extrae características HOG de muchas muestras positivas/negativas y entrena una SVM lineal (scikit-learn), luego fija el detector con setSVMDetector.
import cv2
img = cv2.imread("person.jpg", cv2.IMREAD_GRAYSCALE)
img = cv2.resize(img, (64, 128)) # standard HOG window
hog = cv2.HOGDescriptor((64, 128), (16, 16), (8, 8), (8, 8), 9)
descriptor = hog.compute(img)
print(descriptor.shape) # (3780, 1)
# 9 bins per cell, 7x15 cells, 4 cells per block -> 3780 features
# this is the input vector to a linear SVM classifierEmparejamiento de plantillas
El emparejamiento de plantillas desliza la plantilla por la imagen y computa una puntuación de similaridad — funciona solo para coincidencias exactas (o casi) sin rotación ni cambio de escala. TM_CCOEFF_NORMED es la técnica más robusta; los resultados van en [-1, 1]. Para múltiples coincidencias, umbraliza el mapa de respuesta y aplica supresión de no máximos para evitar detecciones solapadas.
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)Emparejamiento de plantillas multiescala
El emparejamiento de plantillas multiescala fuerza un rango de escalas — lento pero funciona cuando el tamaño de la plantilla en la imagen es desconocido. Aún no puede manejar la rotación; para eso tendrías que barrer también ángulos (muy lento) o usar emparejamiento de características. Para detección de objetos en producción usa un detector entrenado (YOLO, SSD) en lugar de emparejar plantillas.
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)Detección de objetos DNN (YOLO)
El módulo dnn de OpenCV puede correr pesos exportados de YOLO/SSD/Faster-RCNN — útil cuando no puedes instalar un framework completo de DL. El parseo de salida de YOLO es verboso: cada detección tiene centro, tamaño, objetividad y puntuaciones por clase. Aplica siempre NMSBoxes (supresión de no máximos) para colapsar las cajas solapadas en una. Para tiempo real usa YOLOv4-tiny o cambia a ONNX + un backend más rápido.
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 suppressionSegmentación de imágenes
Clustering K-Means
K-means agrupa píxeles por color — una forma simple de posterizar o segmentar una imagen en K colores dominantes. Pasa píxeles float32 como (N, 3) (o (N, 5) si añades coordenadas xy para clustering espacial). Aumentar K da una separación de color más fina. Para coherencia espacial, aumenta cada píxel con sus coordenadas (x, y); para cuantización pura de color, usa solo 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 es un extractor interactivo de primer plano — le das un rectángulo envolvente y modela iterativamente primer plano/fondo con Mezclas Gaussianas. Para resultados más finos, refina con GC_INIT_WITH_MASK tras etiquetar píxeles manualmente (primer plano definitivo / fondo definitivo). Funciona bien para un único objeto saliente contra un fondo relativamente simple.
import cv2
import numpy as np
img = cv2.imread("person.jpg")
h, w = img.shape[:2]
# initialize mask (all probable background)
mask = np.zeros((h, w), np.uint8)
# define a rectangle around the foreground object
rect = (50, 50, w - 100, h - 100)
# internal scratch arrays
bgd = np.zeros((1, 65), np.float64)
fgd = np.zeros((1, 65), np.float64)
# run GrabCut: 5 iterations
cv2.grabCut(img, mask, rect, bgd, fgd, 5, cv2.GC_INIT_WITH_RECT)
# mask values: 0=bg, 1=fg, 2=probable bg, 3=probable fg
fg_mask = np.where((mask == 1) | (mask == 3), 255, 0).astype(np.uint8)
result = cv2.bitwise_and(img, img, mask=fg_mask)Watershed
Watershed trata la imagen como un mapa topográfico (intensidad = elevación) e 'inunda' cuencas desde marcadores semilla — sin buenas semillas produce una sobresegmentación severa. El truco de la transformada de distancia genera semillas de primer plano seguro para objetos que se tocan (por ejemplo, monedas solapadas). Marcadores: 0=desconocido, 1=fondo, 2..N=objetos, -1=frontera. Este es el pipeline clásico de 'separar objetos que se tocan'.
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 es la herramienta de varita mágica — parte de un píxel semilla y rellena la totalidad de los píxeles conectados cuyo color esté dentro de loDiff/upDiff respecto a la semilla (FIXED_RANGE) o al píxel anterior. La máscara debe ser 2 píxeles mayor que la imagen (un borde de 1 píxel por lado). Útil para crecimiento de regiones, reemplazo simple de fondo y selección interactiva.
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 1Componentes conectados
connectedComponents etiqueta cada región blanca con un entero único — más rápido que findContours cuando solo necesitas conteo, área y centroides. connectedComponentsWithStats también devuelve cajas envolventes y áreas. La etiqueta 0 es siempre el fondo. La conectividad por defecto es 8 (diagonales incluidas); pasa connectivity=4 para más estricta. Úsalo para conteo de partículas y análisis de manchas.
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 es una segmentación no paramétrica que 'aplana' las regiones de color similar preservando los bordes — a menudo usado como paso previo antes de la segmentación basada en contornos. sp (radio espacial) controla cuán lejos mira el algoritmo espacialmente; sr (radio de color) controla la tolerancia de color. Valores mayores producen regiones mayores y más suaves.
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)Calibración de cámara
Calibración con tablero de ajedrez
La calibración de cámara halla la matriz intrínseca (distancia focal, punto principal) y los coeficientes de distorsión de lente a partir de imágenes de un patrón conocido (el tablero de ajedrez es el estándar porque las esquinas son fáciles de detectar). Necesitas ~10-20 imágenes desde ángulos variados. cornerSubPix refina las esquinas a precisión subpíxel — esencial para una buena calibración. El tamaño de patrón pasado a findChessboardCorners son las esquinas interiores (cuadros-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)Corregir la distorsión de la imagen
undistort elimina la distorsión de lente radial y tangencial usando los parámetros de calibración. Para vídeo, precomputa los mapas una vez con initUndistortRectifyMap y aplica remap en cada fotograma — mucho más rápido que llamar a undistort repetidamente. getOptimalNewCameraMatrix con alpha=1 conserva la totalidad de los píxeles (con bordes negros); alpha=0 recorta a la región válida.
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]Estimación de pose (ArUco)
Los marcadores ArUco son marcadores fiduciales cuadrados (como códigos QR) usados para estimar pose — dado el tamaño físico del marcador y la calibración de cámara, obtienes su rotación 3D (rvec) y traslación (tvec) respecto a la cámara. Disponible en opencv-contrib. drawFrameAxes dibuja los ejes locales X/Y/Z del marcador — rojo=X, verde=Y, azul=Z, longitud en metros.
import cv2
# load a predefined ArUco dictionary
aruco_dict = cv2.aruco.getPredefinedDictionary(cv2.aruco.DICT_4X4_50)
params = cv2.aruco.DetectorParameters()
detector = cv2.aruco.ArucoDetector(aruco_dict, params)
img = cv2.imread("marker.png")
corners, ids, rejected = detector.detectMarkers(img)
if ids is not None:
cv2.aruco.drawDetectedMarkers(img, corners, ids)
# estimate pose (marker size in meters, camera matrix, distortion)
rvecs, tvecs, _ = cv2.aruco.estimatePoseSingleMarkers(
corners, 0.05, mtx, dist)
for rvec, tvec in zip(rvecs, tvecs):
cv2.drawFrameAxes(img, mtx, dist, rvec, tvec, 0.05)Pose fiducial (solvePnP)
solvePnP (Perspective-n-Point) recupera la pose de la cámara desde N correspondencias 3D-a-2D — necesita al menos 4 puntos. Usa SOLVEPNP_ITERATIVE (por defecto) por exactitud o SOLVEPNP_IPPE para objetivos planos. El rvec es un vector de rotación (eje × ángulo); usa Rodrigues para convertirlo a una matriz 3x3. Es la fundación de la RA basada en marcadores y el seguimiento de 6 grados de libertad.
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)Error de reproyección
El error de reproyección es el estándar de oro de la calidad de calibración — mide cuán lejos aterrizan los puntos 3D proyectados de los puntos 2D detectados. Una buena calibración está por debajo de 0.5 px de media; por encima de 1 px suele indicar un mal conjunto de imágenes, un tamaño de patrón equivocado o desenfoque de movimiento. El error por imagen te ayuda a hallar y descartar malas imágenes de calibración.
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 cornerProfundidad y estéreo
Mapa de disparidad estéreo
StereoBM computa un mapa de disparidad (desplazamiento de píxel entre izquierda/derecha) para un par estéreo rectificado — los objetos más cercanos tienen mayor disparidad. numDisparities debe ser múltiplo de 16; blockSize debe ser impar. La salida es int16 escalada por 16 (divide entre 16.0 para disparidad en píxeles). StereoSGBM (emparejamiento de bloques semiglobal) es más lento pero mucho más preciso.
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 impone suavidad a lo largo de las líneas de escaneo (emparejamiento semiglobal) — mucho más preciso que StereoBM al coste de ~5 veces el runtime. P1/P2 penalizan los cambios de disparidad de 1 y >1 respectivamente; la regla práctica es P1=8*C*blockSize² y P2=32*C*blockSize² donde C es el conteo de canales. Los parámetros speckle* filtran las regiones de disparidad pequeñas y ruidosas.
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)Calibración y rectificación estéreo
El emparejamiento estéreo exige que las imágenes estén rectificadas — líneas epipolares alineadas horizontalmente para que los puntos correspondientes compartan fila. El pipeline es: calibrar cada cámara, calibrar estéreo para hallar R y T entre ellas, stereoRectify para computar las transformaciones de rectificación, y luego remapear cada fotograma una vez. Tras la rectificación, computar la disparidad es una búsqueda 1D a lo largo de las filas.
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)Profundidad a partir de disparidad
La profundidad es inversamente proporcional a la disparidad: profundidad = focal × base / disparidad. La base (separación de cámaras) y la distancia focal deben estar en unidades consistentes (típicamente píxeles para la focal y metros para la base da profundidad en metros). La disparidad es ruidosa para objetos lejanos (poca disparidad, gran error de profundidad) — por eso las cámaras estéreo necesitan una base ancha para rango lejano.
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)Flujo óptico (Lucas-Kanade)
Lucas-Kanade computa flujo óptico disperso — sigue un conjunto de puntos clave entre fotogramas asumiendo movimiento local pequeño. Rápido y preciso para movimiento moderado; falla para movimiento grande o rápido (usa una pirámide, que calcOpticalFlowPyrLK ya hace). status==1 significa que el punto se siguió con éxito. Para flujo denso por píxel usa calcOpticalFlowFarneback — mucho más lento pero produce un campo completo de movimiento.
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()Utilidades y consejos
Medición de rendimiento
TickMeter es la forma más limpia de hacer benchmarks de llamadas OpenCV — getTimeMilli devuelve milisegundos de reloj. getTickCount/getTickFrequency dan tiempos precisos por ciclo. Promedia siempre sobre muchas iteraciones para amortiguar el jitter, y desactiva cv2.imshow al hacer benchmarks (el renderizado de GUI domina). setNumThreads controla el backend paralelo subyacente (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())Eventos de ratón
setMouseCallback registra un manejador para los eventos de ratón en una ventana con nombre — útil para selección interactiva de ROI, herramientas de anotación y apps de pintado simples. Eventos comunes: LBUTTONDOWN, LBUTTONUP, MOUSEMOVE, RBUTTONDOWN. El manejador debe ser una función de nivel superior (o global); los globales son la forma estándar de compartir estado porque la firma del callback es fija.
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
Las trackbars te permiten ajustar parámetros interactivamente sin reiniciar el script — inestimable para hallar buenos umbrales, tamaños de kernel y rangos HSV. El callback se llama en cada cambio (un no-op vale si sondeas getTrackbarPos en el bucle principal). Las trackbars deben crearse sobre una ventana con nombre y leerse con getTrackbarPos(ventana, nombre).
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()Selector de ROI
selectROI abre una ventana interactiva donde el usuario arrastra un rectángulo y pulsa Enter/Espacio — mucho más fácil que escribir tu propio callback de ratón. Pulsa 'c' para cancelar (devuelve solo ceros). selectROIs te permite elegir varios rectángulos uno tras otro. La tupla devuelta es (x, y, w, h); recorta con 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()Trampas comunes
Estas cinco trampas causan la mayoría de bugs de OpenCV: la confusión BGR/RGB (rojo y azul intercambiados), el desbordamiento de uint8 (artefactos oscuros/brillantes), el orden de coordenadas (ROIs desfasadas uno), el None por archivo faltante (las operaciones siguientes caen con errores crípticos) y olvidar waitKey (las ventanas no se actualizan). Interiorízalos pronto — cualquier desarrollador de OpenCV se topa con alguna al menos una vez.
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 blankFragmentos de OpenCV relacionados
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?