Skip to content

OpenCV Folha de referência

Biblioteca open-source de visão computacional e aprendizado de máquina.

01

Primeiros Passos

Ler, Mostrar e Salvar Imagens

OpenCV lê imagens em ordem BGR (não RGB) — pegadinha comum ao interoperar com matplotlib ou PIL. cv2.waitKey(0) bloqueia até uma tecla ser pressionada; sempre chame destroyAllWindows() para fechar janelas. A qualidade do JPEG vai de 0-100.

opencv
import cv2
import numpy as np

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

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

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

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

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

Instalação e Import

opencv-python traz só os módulos principais; opencv-contrib-python adiciona módulos extras (frequentemente restritos por patentes) como SIFT/SURF e ArUco. Use a variante headless em servidores/Docker para evitar puxar dependências do X11. Apesar do nome cv2, o OpenCV 4.x ainda é importado como cv2.

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

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

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

Imagem como Array NumPy

Imagens OpenCV são arrays NumPy, então tudo que você sabe de NumPy se aplica. A convenção de coordenadas é img[y, x] (linha, coluna) — o oposto das coordenadas de imagem (x, y), fonte frequente de bugs. Imagens coloridas são (A, L, 3) em BGR; escala de cinza é (A, L).

opencv
import cv2
import numpy as np

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

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

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

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

Acesso a Pixels e ROI

Acesso pixel a pixel via img[y, x] é lento e desencorajado em loops — sempre prefira slicing NumPy. Use .copy() ao atribuir uma ROI para que mudanças posteriores na fonte não vazem para dentro. Modificar img[:, :, canal] é a forma mais rápida de operar num único canal de cor.

opencv
import cv2
import numpy as np

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

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

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

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

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

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

Tipos de Dados e Conversão

A maioria das funções OpenCV espera uint8 (0-255), mas algoritmos como SIFT, fluxo óptico e detecção de bordas frequentemente precisam de float32. Nunca faça cast direto com .astype() após subtração — overflow de uint8 transforma -1 em 255. Use cv2.absdiff ou converta para float primeiro. Sempre faça cast de volta para uint8 antes de cv2.imwrite / imshow.

opencv
import cv2
import numpy as np

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

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

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

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

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

Captura de Vídeo

Abrir Webcam

VideoCapture(0) abre a webcam padrão; use 1, 2... para câmeras adicionais. Sempre chame cap.release() para liberar o dispositivo — esquecer pode deixar a câmera ocupada para outros apps. waitKey(1) espera ~1ms; o truque & 0xFF garante compatibilidade em sistemas de 64 bits em que waitKey retorna mais de 8 bits.

opencv
import cv2

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

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

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

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

cap.release()
cv2.destroyAllWindows()

Ler Arquivo de Vídeo

CAP_PROP_FRAME_COUNT costuma ser aproximado e não confiável para alguns codecs — não conte com ele para buscas exatas. waitKey(int(1000/fps)) reproduz a uma velocidade aproximadamente correta; para tempo preciso, use um relógio real. Alguns vídeos comprimidos não abrem sem o backend certo (FFmpeg).

opencv
import cv2

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

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

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

cap.release()
cv2.destroyAllWindows()

Salvar / Gravar Vídeo

O código FourCC depende de plataforma e codec: 'mp4v' é amplamente portátil, 'XVID' produz .avi, 'avc1' dá H.264 (pode não estar disponível sem codecs proprietários). O tamanho de quadro passado ao VideoWriter PRECISA casar com os quadros que você grava, senão o arquivo corrompe. Sempre chame out.release() para descarregar e fechar o arquivo.

opencv
import cv2

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

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

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

Configurações de Câmera

Propriedades de câmera dependem de hardware e driver — muitas webcams ignoram silenciosamente configurações não suportadas ou arredondam para o valor válido mais próximo, então sempre leia de volta o valor real. CAP_PROP_EXPOSURE usa log2 de segundos (-4 = 1/16 s). A exposição automática precisa ser desativada (definida como 1) antes que a exposição manual tenha efeito na maioria das câmeras.

opencv
import cv2

cap = cv2.VideoCapture(0)

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

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

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

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

Taxa de Quadros e Tempo

cap.get(CAP_PROP_FPS) retorna o FPS configurado, não a taxa real de captura — meça com um relógio real. Uma média móvel de 30 quadros suaviza jitter. Os maiores assassinos de FPS são cv2.imshow (thread de GUI) e cv2.imwrite por quadro; para benchmarks, desative a exibição. Para tempo determinístico, acumule quadros numa thread e processe de uma fila.

opencv
import cv2
import time

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

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

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

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

cap.release()
cv2.destroyAllWindows()
03

Desenho

Linha e Retângulo

Todas as funções de desenho mutam a imagem no próprio local — passe uma cópia se quiser manter a original. As coordenadas são (x, y), o oposto da indexação [y, x] do NumPy. Cores são tuplas BGR. Use thickness=-1 para formas preenchidas e cv2.LINE_AA para linhas suaves (com anti-aliasing) em bordas diagonais.

opencv
import cv2
import numpy as np

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

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

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

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

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

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

Círculo e Elipse

O parâmetro axes da ellipse é (meiaLargura, meiaAltura) — a largura completa é 2 * axes[0]. angle rotaciona a elipse inteira; startAngle/endAngle desenham arcos parciais (0° = direita, anti-horário). Desenhar arcos parciais é a forma padrão de renderizar fatias de gráfico de pizza ou indicadores de direção de movimento.

opencv
import cv2
import numpy as np

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

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

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

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

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

Polígono e Polylines

polylines aceita uma lista de arrays de pontos, então você pode desenhar múltiplos polígonos numa única chamada. O array de pontos deve ser int32 e remodelado para (-1, 1, 2). Use fillPoly para formas preenchidas; para preenchimentos translúcidos, desenhe num overlay e misture com addWeighted. A flag isClosed liga o último ponto ao primeiro.

opencv
import cv2
import numpy as np

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

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

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

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

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

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

Texto

As fontes embutidas do OpenCV são fontes vetoriais Hershey — não suportam caracteres CJK/chineses. Para texto não latino, renderize com ImageFont do PIL (Pillow) e converta de volta, ou use cv2.freetype do opencv-contrib. getTextSize retorna ((largura, altura), linha_de_base) — útil para centralizar texto ou desenhar uma caixa de fundo atrás dele.

opencv
import cv2
import numpy as np

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

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

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

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

Seta e Marcador

O tipLength do arrowedLine é uma fração do comprimento da linha, então setas mais longas têm pontas proporcionalmente maiores — defina-o explicitamente se quiser tamanhos de ponta de seta consistentes. drawMarker é conveniente para destacar pontos-chave (ex.: features ou cantos detectados); MARKER_TILTED_CROSS dá um marcador em forma de X.

opencv
import cv2
import numpy as np

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

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

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

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

Overlay e Anotação

A técnica de overlay (desenhar numa cópia e depois addWeighted) é a forma padrão de desenhar preenchimentos translúcidos — o OpenCV não tem alfa nativo para formas. Sempre desenhe o texto sólido DEPOIS da mistura, para que fique nítido; desenhar texto no overlay antes da mistura o deixa borrado. Esse padrão está em toda visualização de detecção/segmentação.

opencv
import cv2
import numpy as np

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

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

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

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

Aritmética de Imagens

Soma e Subtração

O cv2.add do OpenCV satura em 255 (250 + 10 = 255), enquanto o + do NumPy dá a volta (250 + 10 = 8, por overflow de uint8). Para imagens, sempre use cv2.add / cv2.subtract — o wrap cria artefatos visíveis de preto/branco. absdiff é o cavalo de batalha para subtração de fundo e detecção de movimento.

opencv
import cv2
import numpy as np

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

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

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

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

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

Mistura e AddWeighted

addWeighted exige que ambas as imagens tenham tamanho e dtype idênticos — redimensione primeiro. O termo gamma soma uma constante a cada pixel, útil para controle de brilho. O clássico fade/dissolver entre duas imagens é só addWeighted com o alfa varrendo de 0 a 1.

opencv
import cv2
import numpy as np

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

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

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

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

Operações Bit a Bit

Operações bit a bit são a forma padrão de aplicar uma máscara: cv2.bitwise_or(src, dst, mask=mascara) copia src para dst só onde a máscara é não zero. A máscara deve ser uma imagem de 8 bits de canal único, em que não zero significa 'manter'. Esta é a fundação da extração de ROI e da substituição de fundo.

opencv
import cv2
import numpy as np

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

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

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

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

Diferença de Imagem e Movimento

Diferença de quadros é o detector de movimento mais simples: binarize a diferença absoluta entre quadros consecutivos. Falha quando a câmera se move e ignora movimento lento — para sistemas reais use subtração de fundo (cv2.createBackgroundSubtractorMOG2) ou fluxo óptico. Abertura morfológica remove ruído; dilatação une blobs próximos.

opencv
import cv2
import numpy as np

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

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

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

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

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

ROI e Mascaramento

bitwise_and com máscara é a forma idiomática de extrair regiões irregulares. A indexação booleana NumPy (img[mascara]) é mais flexível, mas retorna um array plano de pixels, não uma imagem com forma. Sempre faça .copy() das ROIs que planeja reutilizar — o slicing retorna uma view que aponta para a original.

opencv
import cv2
import numpy as np

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

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

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

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

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

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

Saturação vs Enrolamento

A armadilha do overflow uint8: NumPy dá a volta (300 -> 44), OpenCV satura (300 -> 255). Para qualquer aritmética que possa exceder 0-255, use cv2.add/subtract ou promova para int16/float32 primeiro e recorte depois. Misturar operações cv2 e NumPy no mesmo pipeline é a fonte nº 1 de misteriosos artefatos de pixels escuros/claros.

opencv
import cv2
import numpy as np

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

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

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

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

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

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

Transformações Geométricas

Resize / Escala

INTER_AREA é melhor para redução (evita aliasing), INTER_CUBIC ou INTER_LINEAR para ampliação. INTER_NEAREST é a mais rápida, mas blocosa — usada para imagens de rótulo/máscara, em que você não pode introduzir novos valores de pixel. A tupla dsize é (largura, altura), o oposto de img.shape, que é (altura, largura).

opencv
import cv2

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

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

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

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

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

Rotação

cv2.rotate é muito mais rápido que warpAffine para múltiplos de 90°. O ângulo do getRotationMatrix2D está em graus, positivo = anti-horário. Para rotacionar sem cortar, recalcule a bounding box (nova_l, nova_a) e desloque a matriz de rotação — senão os cantos de uma imagem grande rotacionada são cortados.

opencv
import cv2

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

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

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

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

Transformação Afim

Uma transformação afim preserva paralelismo e razões de distâncias — definida por 3 correspondências de pontos (6 graus de liberdade). warpAffine usa mapeamento direto implicitamente via busca inversa, então M mapeia src->dst, mas a função o inverte internamente. Use borderMode=BORDER_REFLECT ou BORDER_CONSTANT para controlar como regiões fora dos limites são preenchidas.

opencv
import cv2
import numpy as np

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

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

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

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

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

Transformação de Perspectiva

Perspectiva (homografia) é definida por 4 pares de pontos não colineares — 8 GL. Esta é a transformação padrão de 'scanner de documentos': pegue os 4 cantos de um cartão/papel na foto e deforme para um retângulo. getPerspectiveTransform precisa de exatamente 4 pontos; para um ajuste superdeterminado use cv2.findHomography com RANSAC.

opencv
import cv2
import numpy as np

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

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

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

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

Flip e Espelho

flip é uma operação barata em memória — muito mais rápida que warpAffine. Convenção de sinal do flipCode: positivo espelha horizontalmente, 0 verticalmente, negativo ambos. cv2.transpose troca os eixos e às vezes é usada como rotação rápida de 90° quando combinada com um flip.

opencv
import cv2

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

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

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

Remap (Mapeamento Personalizado)

remap é a transformação geométrica mais geral — resize, rotação e até correção de distorção de lente/barril podem ser expressos como remap. Sempre construa os mapas com vetorização NumPy, não loops Python (a versão com loop acima é só ilustrativa — ~100x mais lenta). INTER_LINEAR é o padrão; para precisão subpixel nas bordas use INTER_CUBIC.

opencv
import cv2
import numpy as np

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

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

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

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

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

Filtragem de Imagens

Desfoque Médio (Box Filter)

O desfoque médio é o filtro passa-baixa mais simples — substitui cada pixel pela média da sua vizinhança. Os kernels devem ser ímpares e positivos. Kernels maiores desfocam mais, mas também destroem detalhes mais rápido. Use quando você quer especificamente ponderação uniforme; para imagens naturais, o desfoque gaussiano quase sempre é escolha melhor.

opencv
import cv2

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

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

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

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

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

Desfoque Gaussiano

O desfoque gaussiano é o kernel de suavização padrão — pondera os vizinhos por uma gaussiana, preservando bordas melhor que o box filter. Se você passar ksize=(0,0) e sigmaX, o OpenCV computa o tamanho do kernel automaticamente. O desfoque gaussiano é passo prévio obrigatório antes de Canny, redução de resolução e Laplaciano, para suprimir a amplificação de ruído.

opencv
import cv2

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

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

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

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

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

Desfoque de Mediana

O desfoque de mediana é o filtro padrão para ruído sal-e-pimenta (impulso) — substitui cada pixel pela mediana da sua vizinhança, então outliers isolados são removidos em vez de espalhados. Diferente do gaussiano, preserva bem as bordas. O tamanho do kernel deve ser ímpar. É mais lento que gaussiano/box, pois envolve ordenação.

opencv
import cv2

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

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

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

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

Filtro Bilateral

A filtragem bilateral suaviza regiões planas mantendo bordas nítidas — é um filtro não linear que preserva bordas, ponderando vizinhos por proximidade espacial E similaridade de cor. É muito mais lenta que a gaussiana (frequentemente 10x). A aplicação repetida é o clássico passo de pré-processamento do 'cartoonificador'; valores grandes de sigmaColor misturam através de mais cores.

opencv
import cv2

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

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

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

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

Nitidez (Kernel)

Kernels de nitidez enfatizam altas frequências — mas também amplificam ruído, então aplique-os após a remoção de ruído. O kernel clássico de nitidez 3x3 soma 1 (preserva o brilho); soma > 1 clareia. A técnica de unsharp mask (subtrair uma cópia desfocada) é mais controlável e é o que a maioria dos editores de foto realmente usa.

opencv
import cv2
import numpy as np

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

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

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

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

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

Kernel Personalizado (filter2D)

filter2D aplica um kernel de correlação arbitrário — ddepth=-1 mantém a profundidade da fonte. Kernels podem ser float para coeficientes negativos; se o resultado ficar negativo, troque ddepth=cv2.CV_16S ou CV_32F e depois convertScaleAbs de volta. Kernels separáveis (produto externo de kernels 1D) são muito mais rápidos via sepFilter2D.

opencv
import cv2
import numpy as np

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

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

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

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

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

Operações Morfológicas

Erosão e Dilatação

A erosão encolhe regiões de primeiro plano (brancas) e remove pontinhos de ruído; a dilatação as cresce e preenche buracos pequenos. A forma do kernel importa: RECT para uso geral, ELLIPSE para features mais redondas, CROSS para afinar/conectar ao longo dos eixos. iterations=N repete a operação N vezes, equivalente a usar um kernel maior.

opencv
import cv2
import numpy as np

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

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

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

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

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

Abertura e Fechamento

A abertura (erodir→dilatar) remove pontinhos claros pequenos sem mudar o tamanho de objetos maiores. O fechamento (dilatar→erodir) preenche buracos escuros pequenos. São idempotentes — aplicar duas vezes é igual a aplicar uma. O padrão clássico de denoising é fechar-então-abrir (ou abrir-então-fechar) para tratar ambos os tipos de defeito.

opencv
import cv2
import numpy as np

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

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

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

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

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

Gradiente Morfológico

O gradiente morfológico (dilatação - erosão) produz um contorno grosso dos limites dos objetos — útil como detector de bordas rápido ou como máscara para segmentação. Diferente do Canny, dá bordas preenchidas e largas, então serve mais para destacar regiões do que para medir posições exatas de bordas.

opencv
import cv2
import numpy as np

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

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

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

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

Top Hat e Black Hat

Top-hat extrai pequenas estruturas claras menores que o kernel (ex.: texto num documento escuro); black-hat extrai pequenas estruturas escuras. Juntos, são usados para extração de sombra/realce e como corretor rápido de iluminação desigual (o truque de dividir pelo fundo é comum em scanners de documentos).

opencv
import cv2
import numpy as np

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

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

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

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

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

Esqueletização

A esqueletização morfológica afina uma forma binária a um eixo medial de 1 pixel de largura — útil para OCR, análise de impressões digitais e vasos. O loop iterativo erodir-subtrair-abrir roda até a imagem ficar vazia. Para uso em produção, o medial_axis ou thinning do scikit-image é mais rápido e dá resultados mais limpos.

opencv
import cv2
import numpy as np

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

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

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

Hit-or-Miss

Hit-or-miss é o casador de padrões morfológico — encontra configurações exatas de pixels de primeiro plano e fundo, útil para detectar formas específicas como cantos ou junções em T. O kernel usa 1 para primeiro plano obrigatório, -1 para fundo obrigatório, 0 para indiferente. É nicho, mas imbatível para localização exata de padrões.

opencv
import cv2
import numpy as np

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

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

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

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

Detecção de Bordas

Detector de Bordas Canny

Canny é o detector de bordas mais usado: suavização gaussiana → gradientes Sobel → supressão não máxima → histerese (dois limiares). Pixels acima do limiar alto são bordas; os entre o baixo e o alto são bordas só se conectados a uma borda forte. O truque de limiar automático (mediana × 0.7/1.3) funciona bem para imagens variadas.

opencv
import cv2

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

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

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

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

Operador Sobel

Sobel computa a primeira derivada — use ddepth=cv2.CV_64F (ou CV_16S) para capturar gradientes negativos, senão o overflow de uint8 torna invisíveis as transições de escuro para claro. ksize=3 é padrão; ksize=5 dá bordas mais suaves, porém mais largas. A magnitude (sqrt(sx²+sy²)) é a base do Canny e de muitos detectores de features.

opencv
import cv2
import numpy as np

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

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

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

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

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

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

Laplaciano

O Laplaciano é a segunda derivada — muito sensível a ruído, então sempre desfoque primeiro. Detecta cruzamentos por zero (mudanças de sinal), dando bordas finas e precisas, mas sem direção. Mais usado na detecção de bordas de Marr-Hildreth e como entrada do canal 'L' na nitidez de imagens (unsharp mask). Use CV_64F, porque a segunda derivada balança muito para o negativo.

opencv
import cv2
import numpy as np

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

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

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

Filtro Scharr

Scharr é uma variante do Sobel projetada para janelas 3x3 — quando você precisar usar um kernel pequeno, dá direção de gradiente mais precisa que Sobel ksize=3. Para kernels maiores (5x5, 7x7), Sobel serve. cv2.Sobel com ksize=-1 equivale a Scharr. Scharr é preferido quando a direção do gradiente importa (HOG, orientação de bordas).

opencv
import cv2
import numpy as np

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

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

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

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

Pipeline de Detecção de Bordas

O pipeline cinza → denoise → Canny → dilatar → findContours cobre uma enorme fração das tarefas práticas de bordas. A dilatação antes da busca de contornos fecha bordas quebradas que, de outro modo, dividiriam um objeto em vários. Ajustar os limiares do Canny e o tamanho do kernel de denoise é onde vai a maior parte do esforço de engenharia.

opencv
import cv2
import numpy as np

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

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

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

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

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

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

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

Contornos

Encontrar Contornos

findContours muta a imagem fonte no OpenCV 3.x — passe uma cópia se precisar da binária depois. RETR_EXTERNAL retorna só os contornos mais externos (o mais rápido); RETR_TREE dá a hierarquia completa para formas aninhadas (buracos dentro de objetos). CHAIN_APPROX_SIMPLE descarta pontos redundantes ao longo de linhas retas, economizando memória.

opencv
import cv2

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

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

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

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

Desenhar Contornos

drawContours(imagem, contornos, contourIdx, cor, espessura): contourIdx=-1 desenha tudo; um índice específico desenha um. Espessura=-1 preenche o contorno. Desenhar numa imagem em branco é a forma padrão de construir uma máscara de contorno para operações downstream, como cor média ou histograma mascarado.

opencv
import cv2

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

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

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

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

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

Propriedades de Contornos

contourArea é em pixels e ignora buracos (use o contorno com a hierarquia RETR_CCOMP para área líquida). O dicionário de momentos dá o centróide (m10/m00, m01/m00) — proteja contra divisão por zero se m00 for 0 (contornos degenerados). Razão de aspecto e extensão são os descritores de forma mais simples para classificação de formas.

opencv
import cv2

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

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

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

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

Retângulos Delimitadores

boundingRect dá uma caixa alinhada aos eixos (rápida, simples); minAreaRect dá o menor retângulo rotacionado (útil para medir a orientação/tamanho real de um objeto). boxPoints converte o rect rotacionado em 4 pontos de canto que você pode passar ao drawContours. minEnclosingCircle é o menor círculo contendo o contorno.

opencv
import cv2

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

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

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

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

Aproximação de Contornos

approxPolyDP simplifica um contorno para um polígono com menos vértices usando o algoritmo Douglas-Peucker. O epsilon (tipicamente 1-5% do perímetro) controla a tolerância: menor mantém mais detalhe. Contar vértices é o classificador clássico de formas feito à mão — triângulos=3, retângulos=4, círculos=muitos.

opencv
import cv2

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

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

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

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

Casco Convexo e Defeitos

O casco convexo é a menor forma convexa que envolve o contorno — útil para medir a compacidade de objetos e para detecção de mãos/dedos via defeitos de convexidade. A profundidade de cada defeito mede quão 'para dentro' o contorno mergulha em relação ao casco; defeitos profundos na silhueta de uma mão tipicamente correspondem a vãos entre dedos.

opencv
import cv2

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

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

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

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

Binarização (Thresholding)

Limiar Básico

THRESH_BINARY: acima->255, abaixo->0. THRESH_TRUNC: acima->limitado em thresh, abaixo->inalterado. THRESH_TOZERO: acima->inalterado, abaixo->0. O ret retornado iguala o limiar de entrada para binarização simples, mas fica significativo para Otsu/Triangle. Escolha o tipo conforme como quer tratar pixels fora da faixa.

opencv
import cv2

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

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

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

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

Limiar Adaptativo

A binarização adaptativa computa um limiar diferente para cada pixel com base na vizinhança local — essencial para imagens com iluminação desigual (ex.: fotografias de documentos). blockSize deve ser ímpar (tipicamente 11-31) e maior que o tamanho da feature. C subtrai uma constante da média local; aumente-a para suprimir ruído de baixo contraste.

opencv
import cv2

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

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

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

Algoritmo de Otsu

O algoritmo de Otsu acha o limiar global ótimo maximizando a variância entre as classes de primeiro plano e fundo — passe thresh=0 e adicione a flag THRESH_OTSU. Sempre desfoque primeiro; Otsu é sensível a ruído no histograma. O algoritmo Triangle funciona melhor em imagens com um único pico dominante (ex.: microscopia). O ret retornado é o limiar computado.

opencv
import cv2

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

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

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

Limiar de Cor (inRange)

inRange é a ferramenta padrão de segmentação por cor — converta para HSV primeiro, porque separa a cor (hue) do brilho, tornando os limiares robustos a mudanças de iluminação. O hue do vermelho dá a volta em 0/180, então você precisa de duas máscaras combinadas com OR. Sempre desfoca antes do inRange para reduzir pontinhos de ruído na máscara.

opencv
import cv2
import numpy as np

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

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

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

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

Pipeline de Binarização

O pipeline denoise → limiar → morfologia trata a maioria das tarefas de binarização. Escolha Otsu para iluminação uniforme, adaptativo para desigual. O fechamento-então-abertura morfológico remove tanto buracos internos quanto pontinhos externos. Sempre inspecione a máscara binária — os parâmetros de limiar quase sempre são específicos da imagem e precisam de ajuste por dataset.

opencv
import cv2
import numpy as np

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

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

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

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

Binarização para OCR

Para OCR, o gaussiano adaptativo quase sempre supera o Otsu global em documentos fotografados, por causa da iluminação desigual. Casar blockSize com a altura dos caracteres (regra prática: 1-2× a largura do traço × 4). A maioria dos engines de OCR (Tesseract) prefere texto preto em fundo branco — inverta se sua binária estiver ao contrário.

opencv
import cv2

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

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

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

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

Espaços de Cor

BGR / RGB / Cinza

OpenCV lê imagens como BGR por padrão; a maioria das outras bibliotecas (matplotlib, PIL, scikit-image) usa RGB. Esquecer cvtColor é a causa mais comum de imagens 'com vermelho e azul trocados'. A conversão para escala de cinza usa pesos perceptuais (Y = 0.299R + 0.587G + 0.114B), não uma média simples.

opencv
import cv2

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

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

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

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

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

BGR para HSV

O HSV do OpenCV usa H em 0-179 (não 0-360) para caber num uint8 — fonte frequente de bugs de 2x ao portar código de outras bibliotecas. S e V vão de 0-255. HSV é o espaço preferido para segmentação por cor, porque o hue é aproximadamente invariante a mudanças de brilho — use para rastreamento de objetos por cor.

opencv
import cv2
import numpy as np

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

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

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

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

BGR para LAB

CIELAB aproxima a percepção humana — mudanças numéricas iguais parecem aproximadamente igualmente diferentes, razão pela qual é usado em métricas de diferença de cor (ΔE). O canal L codifica só a luminosidade, então editar L é a forma mais limpa de clarear uma imagem sem deslocar cores. O LAB do OpenCV usa 0-255 para cada um dos canais, não o padrão 0-100 para L.

opencv
import cv2

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

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

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

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

Rastreamento de Cor (HSV)

O rastreamento de cor baseado em HSV é o rastreador de objetos mais simples — escolha a faixa de hue, binarize, ache o maior blob. Falha sob iluminação ruim (baixa saturação), com objetos de fundo de cor similar e em superfícies refletoras. Para rastreamento robusto, combine com camshift/meanshift (usa retroprojeção de histograma de hue) ou um filtro de Kalman para suavizar o movimento.

opencv
import cv2
import numpy as np

cap = cv2.VideoCapture(0)

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

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

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

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

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

cap.release()

Split e Merge de Canais

split/merge são convenientes, mas mais lentos que indexação NumPy — img[:, :, 0] é o canal azul e modificá-lo é mais rápido que split. Sempre passe os canais ao merge na ordem correta para o espaço de cor alvo. O truque de 'zerar dois canais' é a forma clássica de visualizar a contribuição de um único canal de cor.

opencv
import cv2
import numpy as np

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

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

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

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

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

Outros Espaços de Cor

YCrCb separa luminância (Y) de croma (Cr, Cb) — a base da compressão JPEG e MPEG, que descarta detalhe de croma porque humanos são menos sensíveis à cor que ao brilho. HLS difere do HSV em que o branco está em L=1 independentemente da saturação, tornando HLS melhor para alguns efeitos de sombreamento. Escolha o espaço que torna sua operação invariante ao que você não se importa.

opencv
import cv2

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

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

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

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

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

Histogramas

Calcular Histograma

calcHist recebe uma lista de imagens, uma lista de canais, uma máscara opcional (None = imagem inteira), a contagem de bins e a faixa de valores. Para histogramas multidimensionais (ex.: hue-saturação 2-D), passe dois canais e dois tamanhos de bin — usado na retroprojeção de histograma para rastreamento de cor. O histograma de cada canal é computado independentemente.

opencv
import cv2
import numpy as np

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

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

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

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

Plotar Histograma

Matplotlib é a forma mais fácil de visualizar histogramas — mas lembre de converter BGR para RGB para as cores da legenda, senão as cores do seu gráfico não casam com os rótulos dos canais. Um histograma inclinado à esquerda é uma imagem escura, à direita clara; um pico estreito significa baixo contraste. Use isto para diagnosticar problemas de exposição e balanço de branco.

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

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

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

Equalização de Histograma

A equalização de histograma estica as intensidades dos pixels para usar toda a faixa 0-255 — ótima para imagens de baixo contraste, mas pode estourar realces e amplificar ruído. NUNCA equalize os três canais BGR diretamente — isso desloca cores. Sempre converta para um espaço de luminância/crominância (YCrCb, LAB, HSV), equalize a luminância e converta de volta.

opencv
import cv2

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

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

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

CLAHE (Equalização Adaptativa)

CLAHE é a alternativa de qualidade de produção à equalização global — opera em ladrilhos pequenos, então funciona em imagens com iluminação desigual, e clipLimit limita a amplificação de contraste para não explodir o ruído. tileGridSize de 8x8 é o padrão; ladrilhos menores dão mais adaptação local. A escolha padrão em imagens médicas e aprimoramento de documentos.

opencv
import cv2

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

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

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

Retroprojeção de Histograma

A retroprojeção de histograma responde 'onde os pixels se parecem com a distribuição de cores da minha ROI?'. Construa um histograma hue-saturação 2-D de uma amostra e depois retroprojete numa imagem alvo para obter um mapa de probabilidade. É a base do rastreamento meanShift/camShift — muito mais robusto que uma faixa HSV fixa, porque aprende a distribuição real de cores do alvo.

opencv
import cv2
import numpy as np

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

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

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

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

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

Detecção de Features

Detector de Cantos de Harris

Harris detecta cantos verificando se mover uma pequena janela em qualquer direção causa uma grande mudança de intensidade — cantos mudam em todas as direções, bordas em uma, regiões planas em nenhuma. A saída é um mapa de resposta de canto; binarize relativo ao máximo (ex.: 0.01 * max). blockSize é a vizinhança para o cálculo do tensor de estrutura.

opencv
import cv2
import numpy as np

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

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

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

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

Shi-Tomasi (goodFeaturesToTrack)

Shi-Tomasi melhora Harris usando min(autovalor1, autovalor2) como pontuação, o que dá cantos mais estáveis para rastreamento. maxCorners limita a contagem; qualityLevel é uma fração da resposta de canto mais forte (0.01 = 1% do melhor); minDistance impõe separação espacial entre cantos detectados. Esta é a entrada padrão para o rastreador de fluxo óptico Lucas-Kanade.

opencv
import cv2
import numpy as np

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

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

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

SIFT (Features Invariantes a Escala)

SIFT acha keypoints invariantes a escala e rotação e um descritor 128-D para cada — robusto a iluminação, ponto de vista e oclusão parcial. Foi patenteado por anos e ficou gratuito no OpenCV 4.4. Use SIFT para casamento de alta precisão onde a velocidade é secundária. DRAW_RICH_KEYPOINTS desenha a escala e a orientação de cada keypoint.

opencv
import cv2

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

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

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

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

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

ORB (FAST + BRIEF)

ORB combina o detector de keypoints FAST com o descritor BRIEF — ambos livres de patentes e ~10x mais rápidos que SIFT, tornando ORB a escolha padrão para casamento em tempo real em mobile/embedded. Os descritores são binários (32 bytes vs 128 floats do SIFT), então o casamento usa distância de Hamming. Um pouco menos robusto que SIFT a escala/rotação, mas excelente pelo custo.

opencv
import cv2

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

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

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

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

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

Detector FAST

FAST testa se um círculo de 16 pixels ao redor de um candidato tem N pixels contíguos uniformemente mais claros ou uniformemente mais escuros que o centro — extremamente rápido, porque curto-circuita. Retorna só keypoints, sem descritores (use BRIEF ou ORB para descritores). Limiar menor = mais cantos (e mais ruidosos); a supressão não máxima remove duplicatas nos máximos locais.

opencv
import cv2

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

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

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

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

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

MSER (Regiões Extremais Estáveis)

MSER acha regiões que permanecem estáveis numa faixa de limiares de intensidade — ideal para detecção de texto (onde letras são tipo blob), placas de carro e texto de cena. Trata bem iluminação desigual, porque cada região é detectada no seu próprio limiar. Filtre os resultados por razão de aspecto e tamanho para remover não-texto óbvio.

opencv
import cv2

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

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

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

Casamento de Features

Casamento por Força Bruta

O casamento por força bruta tenta cada par de descritores — exato, mas O(N*M). Para os descritores binários do ORB use NORM_HAMMING; para descritores float de SIFT/SURF use NORM_L2. crossCheck=True mantém só os melhores matches mútuos (o melhor de A é B e vice-versa), o que remove muitos falsos positivos. Cada match tem um .distance — menor é melhor.

opencv
import cv2

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

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

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

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

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

Casamento FLANN

FLANN (Fast Library for Approximate Nearest Neighbors) constrói uma KD-tree (para SIFT/SURF) ou LSH (para ORB) para achar matches aproximados — muito mais rápido que força bruta em grandes conjuntos de descritores, ao custo de falhas ocasionais. Os parâmetros trees e checks trocam precisão por velocidade. Use FLANN quando tiver milhares de features; força bruta serve para conjuntos pequenos.

opencv
import cv2
import numpy as np

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

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

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

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

Casamento KNN e Teste de Razão

O teste de razão de Lowe é o filtro padrão para casamento de features: mantenha um match só se o melhor for significativamente mais próximo que o segundo melhor (limiar típico 0.7-0.8). A intuição: se ambos os candidatos estão igualmente próximos, o match é ambíguo e provavelmente errado. Esse único teste remove a vasta maioria dos falsos positivos.

opencv
import cv2

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

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

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

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

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

Homografia (RANSAC)

findHomography com RANSAC computa a transformação de perspectiva que mapeia src em dst ignorando outliers — a máscara de inliers diz quais matches concordam com o modelo. O limiar de reprojeção (5.0) está em pixels; menor = mais estrito. Você precisa de pelo menos 4 bons matches. Use isto para localizar um objeto conhecido numa cena ou alinhar fotos sobrepostas.

opencv
import cv2
import numpy as np

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

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

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

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

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

Localização de Objetos

Este é o pipeline clássico de localização de objetos: detecte features em ambas as imagens, case-as, ajuste uma homografia com RANSAC e depois projete a bounding box do objeto na cena. Funciona para objetos planos ou objetos 3D distantes (onde a perspectiva domina). Falha em objetos sem textura, simétricos ou altamente ocluídos — para esses use detectores de deep learning.

opencv
import cv2
import numpy as np

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

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

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

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

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

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

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

Detecção de Rostos

Classificador Haar Cascade

Haar cascades são o detector clássico Viola-Jones — rápido na CPU e bom para rostos frontais, mas menos preciso que detectores modernos de deep learning (MTCNN, SSD, RetinaFace). scaleFactor (>1) controla a busca multi-escala — 1.1 = passo de escala de 10%; menor = mais lento, porém mais completo. minNeighbors filtra detecções sobrepostas; aumente para reduzir falsos positivos.

opencv
import cv2

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

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

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

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

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

Detectar Rostos em Imagem

Detectar olhos (ou sorriso) dentro da ROI do rosto é o truque de eficiência padrão: buscar olhos na imagem inteira dá muitos falsos positivos, mas dentro de uma ROI de rosto confirmada são raros. cv2.data.haarcascades aponta para o diretório de XMLs incluídos — outros cascades (olho, sorriso, corpo inteiro, placa) estão disponíveis. Recorte a ROI ANTES de chamar o cascade.

opencv
import cv2

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

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

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

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

Detectar Rostos em Vídeo

Detecção de rostos em tempo real na webcam é viável na CPU graças à velocidade dos Haar cascades. O truque de desfocar a ROI (GaussianBlur só na região do rosto) é uma técnica simples de privacidade/anonimização. Para rastrear rostos entre quadros (evitar tremedeira), associe detecções por IoU e suavize com um filtro de Kalman — cascades sozinhos não têm continuidade temporal.

opencv
import cv2

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

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

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

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

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

cap.release()
cv2.destroyAllWindows()

Rosto de Perfil / Lateral

Haar cascades são específicos de pose — o cascade frontal perde rostos de lado, então combine com o cascade de perfil. Como o cascade de perfil é treinado num lado, detecte o outro lado espelhando a imagem horizontalmente e espelhando de volta as coordenadas resultantes. Isso ainda perde visões 3/4; detectores modernos (DNN, MTCNN) tratam todas as poses num único modelo.

opencv
import cv2

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

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

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

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

Detecção de Rostos com DNN

O módulo dnn do OpenCV pode rodar modelos pré-treinados Caffe/TensorFlow/ONNX — detectores de rosto baseados em SSD e ResNet são muito mais precisos que Haar cascades e tratam todas as poses num único modelo. blobFromImage faz subtração de média e escala numa tacada só. As detecções são normalizadas [0,1] — multiplique por (l, a, l, a) para obter caixas em pixels. Modelos: SSD (Caffe), YuNet (ONNX, via cv.FaceDetectorYN).

opencv
import cv2
import numpy as np

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

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

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

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

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

Detecção de Objetos

Descritor HOG

HOG (Histogram of Oriented Gradients) descreve a forma local por histogramas de direções de bordas — combinado com um SVM linear, é um detector de objetos clássico. O detector de pessoas pré-treinado funciona para pedestres de corpo inteiro em poses eretas. winStride e scale trocam velocidade por recall. Detectores profundos modernos (YOLO, SSD) são muito mais precisos, mas HOG roda na CPU sem arquivo de modelo.

opencv
import cv2

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

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

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

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

Visualização de Features HOG

A janela HOG padrão é 64x128 pixels (o tamanho de pedestre do INRIA). Parâmetros: janela (64x128), bloco (16x16), passo de bloco (8x8), célula (8x8), bins (9). Cada descritor tem 3780-D. Para classificar objetos personalizados, extraia features HOG de muitas amostras positivas/negativas e treine um SVM linear (scikit-learn), depois defina o detector com setSVMDetector.

opencv
import cv2

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

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

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

Casamento de Templates

O casamento de templates desliza o template pela imagem e computa uma pontuação de similaridade — funciona só para matches exatos (ou quase exatos), sem rotação nem mudança de escala. TM_CCOEFF_NORMED é a opção mais robusta; os resultados vão de [-1, 1]. Para múltiplos matches, binarize o mapa de resposta e aplique supressão não máxima para evitar detecções sobrepostas.

opencv
import cv2
import numpy as np

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

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

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

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

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

Casamento de Templates Multi-escala

O casamento de templates multi-escala varre por força bruta uma faixa de escalas — lento, mas funciona quando o tamanho do template na imagem é desconhecido. Ainda não trata rotação; para isso você precisaria varrer ângulos também (muito lento) ou usar casamento de features. Para detecção de objetos em produção, use um detector treinado (YOLO, SSD) em vez de casamento de templates.

opencv
import cv2
import numpy as np

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

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

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

Detecção de Objetos com DNN (YOLO)

O módulo dnn do OpenCV pode rodar pesos exportados YOLO/SSD/Faster-RCNN — útil quando você não pode instalar um framework de DL completo. O parsing da saída do YOLO é verboso: cada detecção tem centro, tamanho, objetividade e pontuações por classe. Sempre aplique NMSBoxes (supressão não máxima) para colapsar caixas sobrepostas numa só. Para tempo real use YOLOv4-tiny ou troque para ONNX + um backend mais rápido.

opencv
import cv2
import numpy as np

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

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

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

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

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

Segmentação de Imagens

Clustering K-Means

K-means agrupa pixels por cor — uma forma simples de posterizar ou segmentar uma imagem nas K cores dominantes. Passe pixels float32 como (N, 3) (ou (N, 5) se adicionar coordenadas xy para clustering espacial). Aumentar K dá separação de cores mais fina. Para coerência espacial, acrescente a cada pixel suas coordenadas (x, y); para pura quantização de cor, use só BGR.

opencv
import cv2
import numpy as np

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

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

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

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

GrabCut

GrabCut é um extrator de primeiro plano interativo — você dá um retângulo delimitador e ele modela iterativamente primeiro plano/fundo com Misturas Gaussianas. Para resultados mais finos, refine com GC_INIT_WITH_MASK depois de rotular pixels manualmente (primeiro plano certo / fundo certo). Funciona bem para um único objeto saliente contra um fundo relativamente simples.

opencv
import cv2
import numpy as np

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

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

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

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

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

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

Watershed

Watershed trata a imagem como um mapa topográfico (intensidade = elevação) e 'inunda' bacias a partir de marcadores de semente — sem boas sementes produz severa sobre-segmentação. O truque da transformada de distância gera sementes de primeiro plano certo para objetos que se tocam (ex.: moedas sobrepostas). Marcadores: 0=desconhecido, 1=fundo, 2..N=objetos, -1=fronteira. É o pipeline clássico de 'separar objetos que se tocam'.

opencv
import cv2
import numpy as np

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

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

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

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

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

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

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

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

Flood Fill

floodFill é a ferramenta varinha mágica — parta de um pixel semente e preencha cada um dos pixels conectados cuja cor esteja dentro de loDiff/upDiff da semente (FIXED_RANGE) ou do pixel anterior. A máscara deve ser 2 pixels maior que a imagem (uma borda de 1 pixel de cada lado). Útil para crescimento de região, substituição simples de fundo e seleção interativa.

opencv
import cv2

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

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

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

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

Componentes Conectados

connectedComponents rotula cada região branca com um inteiro único — mais rápido que findContours quando você só precisa de contagem, área e centróides. connectedComponentsWithStats também retorna bounding boxes e áreas. O rótulo 0 é sempre o fundo. A conectividade padrão é 8 (diagonais incluídas); passe connectivity=4 para mais estrita. Use para contagem de partículas e análise de blobs.

opencv
import cv2
import numpy as np

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

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

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

Mean-Shift / PyrMeanShiftFiltering

pyrMeanShiftFiltering é uma segmentação não paramétrica que 'achata' regiões de cor similar preservando bordas — frequentemente usada como passo de pré-processamento antes de segmentação baseada em contornos. sp (raio espacial) controla quão longe o algoritmo olha espacialmente; sr (raio de cor) controla a tolerância de cor. Valores maiores produzem regiões maiores e mais suaves.

opencv
import cv2

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

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

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

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

Calibração de Câmera

Calibração com Tabuleiro de Xadrez

A calibração de câmera acha a matriz intrínseca (distância focal, ponto principal) e os coeficientes de distorção da lente a partir de imagens de um padrão conhecido (tabuleiro de xadrez é padrão, porque os cantos são fáceis de detectar). Você precisa de ~10-20 imagens de ângulos variados. cornerSubPix refina cantos para precisão subpixel — essencial para uma boa calibração. O tamanho de padrão passado ao findChessboardCorners é de cantos internos (quadrados-1).

opencv
import cv2
import numpy as np
import glob

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

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

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

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

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

Corrigir Distorção da Imagem

undistort remove a distorção radial e tangencial da lente usando os parâmetros de calibração. Para vídeo, pré-compute os mapas uma vez com initUndistortRectifyMap e aplique remap a cada quadro — muito mais rápido que chamar undistort repetidamente. getOptimalNewCameraMatrix com alpha=1 mantém cada um dos pixels (com bordas pretas); alpha=0 recorta para a região válida.

opencv
import cv2
import numpy as np

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

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

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

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

Estimativa de Pose (ArUco)

Marcadores ArUco são marcadores fiduciais quadrados (como QR codes) usados para estimativa de pose — dado o tamanho físico do marcador e a calibração da câmera, você obtém sua rotação 3-D (rvec) e translação (tvec) relativas à câmera. Disponível no opencv-contrib. drawFrameAxes desenha os eixos locais X/Y/Z do marcador — vermelho=X, verde=Y, azul=Z, comprimento em metros.

opencv
import cv2

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

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

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

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

Pose Fiducial (SolvePnP)

solvePnP (Perspective-n-Point) recupera a pose da câmera a partir de N correspondências 3-D-para-2-D — precisa de pelo menos 4 pontos. Use SOLVEPNP_ITERATIVE (padrão) para precisão ou SOLVEPNP_IPPE para alvos planos. O rvec é um vetor de rotação (eixo × ângulo); use Rodrigues para converter numa matriz 3x3. É a fundação da AR baseada em marcadores e do rastreamento de 6 GL.

opencv
import cv2
import numpy as np

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

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

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

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

Erro de Reprojeção

O erro de reprojeção é o padrão-ouro da qualidade de calibração — mede quão longe os pontos 3-D projetados caem dos pontos 2-D detectados. Uma boa calibração fica abaixo de 0.5 px de média; acima de 1 px geralmente indica um conjunto ruim de imagens, tamanho de padrão errado ou motion blur. O erro por imagem ajuda a achar e descartar imagens ruins de calibração.

opencv
import cv2
import numpy as np

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

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

Profundidade e Estéreo

Mapa de Disparidade Estéreo

StereoBM computa um mapa de disparidade (offset de pixel entre esquerda/direita) para um par estéreo retificado — objetos mais próximos têm disparidade maior. numDisparities deve ser múltiplo de 16; blockSize deve ser ímpar. A saída é int16 escalada por 16 (divida por 16.0 para disparidade em pixels). StereoSGBM (casamento de blocos semiglobal) é mais lento, mas muito mais preciso.

opencv
import cv2

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

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

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

StereoSGBM

StereoSGBM impõe suavidade entre linhas de varredura (casamento semiglobal) — muito mais preciso que StereoBM ao custo de ~5x de runtime. P1/P2 penalizam mudanças de disparidade de 1 e >1, respectivamente; regra prática é P1=8*C*blockSize² e P2=32*C*blockSize², em que C é a contagem de canais. Os parâmetros speckle* filtram regiões pequenas e ruidosas de disparidade.

opencv
import cv2

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

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

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

Calibração e Retificação Estéreo

O casamento estéreo exige que as imagens estejam retificadas — linhas epipolares alinhadas horizontalmente, para que pontos correspondentes compartilhem uma linha. O pipeline é: calibrar cada câmera, calibrar estéreo para achar R e T entre elas, stereoRectify para computar as transformações de retificação, e depois remap de cada quadro uma vez. Após a retificação, o cálculo da disparidade é uma busca 1-D ao longo das linhas.

opencv
import cv2
import numpy as np

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

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

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

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

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

Profundidade a partir da Disparidade

A profundidade é inversamente proporcional à disparidade: profundidade = focal × base / disparidade. A base (separação das câmeras) e a distância focal devem estar em unidades consistentes (tipicamente pixels para focal, metros para base dá profundidade em metros). A disparidade é ruidosa para objetos distantes (disparidade pequena, grande erro de profundidade) — por isso câmeras estéreo precisam de base larga para alcance distante.

opencv
import cv2
import numpy as np

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

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

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

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

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

Fluxo Óptico (Lucas-Kanade)

Lucas-Kanade computa fluxo óptico esparso — rastreia um conjunto de keypoints entre quadros assumindo movimento local pequeno. Rápido e preciso para movimento moderado; falha em movimento grande ou rápido (use uma pirâmide, o que calcOpticalFlowPyrLK já faz). status==1 significa que o ponto foi rastreado com sucesso. Para fluxo denso por pixel use calcOpticalFlowFarneback — muito mais lento, mas produz um campo de movimento completo.

opencv
import cv2
import numpy as np

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

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

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

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

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

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

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

cap.release()
20

Utilitários e Dicas

Medição de Desempenho

TickMeter é a forma mais limpa de medir chamadas OpenCV — getTimeMilli retorna milissegundos de relógio. getTickCount/getTickFrequency dão tempo com precisão de ciclo. Sempre faça média de muitas iterações para amortizar jitter, e desative cv2.imshow ao medir (a renderização da GUI domina). setNumThreads controla o backend paralelo subjacente (TBB/OpenMP).

opencv
import cv2
import numpy as np

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

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

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

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

Eventos de Mouse

setMouseCallback registra um handler para eventos de mouse numa janela nomeada — útil para seleção interativa de ROI, ferramentas de anotação e apps simples de pintura. Eventos comuns: LBUTTONDOWN, LBUTTONUP, MOUSEMOVE, RBUTTONDOWN. O handler deve ser uma função de topo (ou global); globais são a forma padrão de compartilhar estado, porque a assinatura do callback é fixa.

opencv
import cv2
import numpy as np

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

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

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

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

Trackbar

Trackbars permitem ajustar parâmetros interativamente sem reiniciar o script — inestimável para achar bons limiares, tamanhos de kernel e faixas HSV. O callback é chamado a cada mudança (uma no-op serve, se você sondar getTrackbarPos no loop principal). Trackbars devem ser criadas numa janela nomeada e lidas com getTrackbarPos(janela, nome).

opencv
import cv2
import numpy as np

def nothing(x):
    pass

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

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

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

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

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

cv2.destroyAllWindows()

Seletor de ROI

selectROI abre uma janela interativa em que o usuário arrasta um retângulo e pressiona Enter/Espaço — muito mais fácil que escrever seu próprio callback de mouse. Pressione 'c' para cancelar (retorna só zeros). selectROIs permite escolher múltiplos retângulos um após o outro. A tupla retornada é (x, y, l, a); recorte com img[y:y+a, x:x+l].

opencv
import cv2

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

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

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

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

Armadilhas Comuns

Estas cinco armadilhas causam a maioria dos bugs de OpenCV: confusão BGR/RGB (vermelho e azul trocados), overflow uint8 (artefatos escuros/claros), ordem de coordenadas (ROIs deslocadas de um), None por arquivo ausente (operações seguintes caem com erros crípticos) e esquecer waitKey (janelas não atualizam). Introduza-as cedo — cada desenvolvedor OpenCV esbarra em cada uma pelo menos uma vez.

opencv
import cv2
import numpy as np

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

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

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

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

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

Was this helpful?

Learning path

Learn from scratch

Learn this language from the ground up with structured lessons.