Este post documenta o que aprendi ao implementar um sistema de inferência CV para segmentação, classificação e mensuração métrica de feridas crônicas. O foco é arquitetura, algoritmos e decisões de engenharia.
\nEste post resume o que estudei, aprendi, e apliquei ao longo desse caminho.
\nAvaliar feridas crônicas envolve duas tarefas distintas de visão computacional:
\nMas há um terceiro desafio, que só aparece quando você coloca o sistema no mundo real: como converter pixels em centímetros? Sem escala espacial, uma máscara bonita ainda não responde à pergunta que importa: qual é a área da ferida?
\nEsse detalhe mudou completamente minha forma de pensar sobre CV.
\nO pipeline é distribuído em três camadas:
\n| Camada | \nStack | \nResponsabilidade | \n
|---|---|---|
| Mobile | \nReact Native / Expo | \nCaptura, upload via presigned URL S3 | \n
| Backend | \nNestJS + MongoDB | \nAuth JWT, metadados clínicos, orquestração | \n
| CV Service | \nFastAPI + PyTorch/OpenCV | \nInferência, pós-processamento, geometria, calibração | \n
O serviço CV expõe POST /infer (JSON { image_url } ou multipart file), autenticado via header x-api-key, com cache Redis (SHA-256 do payload) e rate limiting (60 req/min).
Além dos algoritmos, aprendi a estruturar um serviço de inferência de produção:
\nA lição: em CV aplicada, observabilidade importa tanto quanto acurácia. Sem debug visual, você debugga no escuro.
\nDois modelos rodam em produção:
\ntorch.jit.trace)timm) → ONNX opset 17 com batch dinâmicoPara segmentação, usei uma U-Net com encoder EfficientNet-B3, pré-treinado no ImageNet, via segmentation_models_pytorch. A escolha faz sentido: EfficientNet oferece um bom equilíbrio entre capacidade e eficiência, e a U-Net é o padrão de ouro para máscaras semânticas.
\nsmp.Unet(\n\nencoder_name="efficientnet-b3",\n\nencoder_weights="imagenet",\n\nin_channels=3,\n\nclasses=1,\n\n)\n| Hiperparâmetro | \nValor | \n
|---|---|
| Loss | \nDiceLoss(mode="binary") | \n
| Optimizer | \nAdamW, lr = 1e-3 | \n
| Batch size | \n4 | \n
| Image size | \n512×512 | \n
| Early stopping | \npatience = 5 (maximize val Dice) | \n
| Mixed precision | \nAMP (GradScaler) | \n
Augmentações (albumentations):
A.Resize(512, 512)\n\nA.HorizontalFlip(p=0.5)\n\nA.VerticalFlip(p=0.2)\n\nA.RandomRotate90(p=0.5)\n\nA.ShiftScaleRotate(shift_limit=0.05, scale_limit=0.1, rotate_limit=20, p=0.5)\n\nA.ColorJitter(p=0.3)\n\nA.Normalize()\nExportei o modelo para TorchScript, o que me ensinou que o caminho treino → produção tem requisitos próprios: normalização idêntica, tamanho de entrada fixo e cuidado com operadores suportados na exportação.
\nEfficientNet-B3 via timm, BCEWithLogitsLoss, lr = 3e-4, batch = 8, image size = 384. Métrica: F1.
# TorchScript (seg)\n\nscripted = torch.jit.trace(model, dummy_input) *# dummy: (1, 3, 512, 512)*\n\n# ONNX (cls)\n\ntorch.onnx.export(..., opset_version=17, dynamic_axes={"input": {0: "batch"}})\nConstraint crítico: a normalização e o resize da inferência devem ser idênticos ao treino. Qualquer divergência degrada a distribuição de logits da U-Net e desloca o threshold ótimo de binarização.
\nFluxo completo em run_inference_pipeline():
original (HxW) → cap MAX_WORKING_DIMENSION=1536 (INTER_AREA) → preprocess_mobile_rgb (CLAHE + brightness norm + unsharp) → letterbox 512×512 (scale = 512/max(h,w), pad simétrico) → tensor (C,H,W) normalizado → U-Net → prob map (512×512) → unletterbox → working resolution → postprocess_wound_mask (threshold sweep + morfologia + CC) → extract_wound_geometry (PCA + minAreaRect + Feret) → overlay PNG base64
\nA mesma informação de forma mais bonita:
\n![\"Diagrama](\"/media/diagrama.png\")
\nDado target_size = 512:
scale = target_size / max(h, w)\n\ncontent_w = round(w * scale)\n\ncontent_h = round(h * scale)\n\npad_left = (512 - content_w) // 2\n\npad_top = (512 - content_h) // 2\nA máscara inferida é recortada da região [pad_top:pad_top+content_h, pad_left:pad_left+content_w] e redimensionada para (working_h, working_w) com INTER_NEAREST (preserva binarização).
Por que importa: resize direto para 512×512 distorce aspect ratio e altera a geometria da ferida. Letterbox mantém proporções; o custo é propagar LetterboxMeta (scale, pad_left, pad_top) em todo o pipeline.
Aplicado no espaço LAB (preserva crominância):
\nclipLimit=2.0, tileGridSize=(8,8)mean(gray) < 90 ou > 200, escala por α = clip(128/mean, 0.85, 1.15)out = 1.25·img - 0.25·GaussianBlur(img, σ=1.0)Ativado via MOBILE_IMAGE_PREPROCESS=true. Não altera geometria — apenas distribuição de intensidade.
Entrada: mapa probabilístico P ∈ [0,1]^{H×W}. Saída: máscara binária + contorno + geometry_confidence.
Em vez de um threshold fixo, implementei um sweep automático (0.35, 0.40, 0.45, 0.50, 0.55) que escolhe o valor que gera componentes utilizáveis. Depois:
\nsweep = [0.35, 0.40, 0.45, 0.50, 0.55] # default produção
binary_t = (GaussianBlur(P, k=3) > t).astype(uint8)
Para cada t, computa score baseado em componentes conectados utilizáveis. Seleciona o threshold com melhor score.
Observação empírica: threshold 0.65 (comum em papers) produz máscaras vazias em fotos mobile com logits calibrados para distribuição diferente do val set. Default de produção: 0.40.
\nopen: kernel 3×3, 1 iteração (remove ruído pontual)
\nclose: kernel 5×5, 1 iteração (fecha buracos internos)
\nParâmetros tunáveis via env (MASK_OPEN_KERNEL, MASK_CLOSE_KERNEL).
cv2.connectedComponentsWithStats → filtros em cascata:
| Filtro | \nDefault | \nFunção | \n
|---|---|---|
max_area_fraction | \n0.50 | \nRejeita blob > 50% da imagem | \n
max_aspect_ratio | \n10.0 | \nRejeita estruturas filamentares | \n
min_compactness | \n0.04 | \n4π·A / P² — rejeita formas irregulares demais | \n
min_solidity | \n0.15 | \nA / A_convex_hull | \n
min_area_fraction | \n0.0002 | \nÁrea mínima relativa | \n
min_dimension_px | \n12 | \nDimensão mínima do bbox | \n
Seleção em 3 níveis:
\nMASK_ALLOW_PLAUSIBLE_FALLBACK=true)Isso evita o cenário clássico: modelo acerta parcialmente a ferida, mas CC analysis descarta o único componente válido.
\nAntes de extrair contorno, validate_wound_presence() verifica se prob_max e area_fraction@0.5 excedem limites mínimos. Falha → WoundNotDetectedError com prob_max no payload técnico.
Aprendi que pós-processamento é metade do produto em segmentação médica. O modelo diz onde provavelmente está a ferida; o pipeline decide o que mostrar ao clínico.
\nO Contrast Limited Adaptive Histogram Equalization melhora contraste local em fotos com sombras ou pele escura/clara desigual. É processamento clássico de CV, mas faz diferença real antes da inferência neural.
\nEsta foi uma das partes mais interessantes do projeto: traduzir cor percebida em percentuais clínicos sem treinar um classificador de cor separado.
\nNa prática de curativos, a coloração do leito da ferida orienta conduta. O sistema mapeia pixels para seis categorias inspiradas na escala RYB (Red-Yellow-Black), estendida com roxo e branco:
\n| Classe | \nInterpretação clínica (heurística) | \n
|---|---|
| Vermelho | \nGranulação — tecido de cicatrização | \n
| Amarelo | \nEsfacelo — possível necessidade de desbridamento | \n
| Preto | \nNecrose/eschar — desbridamento | \n
| Roxo | \nHematoma/equimose perilesional | \n
| Branco | \nTecido pálido/isquêmico, biofilme | \n
| Outros | \nPixels que não se encaixam nas regras | \n
A API retorna isso via WoundColorAnalysis (Pydantic), com valores em percentual (0–100) arredondados a 2 casas:
\nclass WoundColorAnalysis(BaseModel):\n vermelho: float # granulação\n amarelo: float # esfacelo/infecção\n preto: float # necrose\n roxo: float # hematoma\n branco: float # isquêmico/biofilme\n outros: float\n\nNo mobile, os percentuais alimentam a tela de nova ferida, o TissueColorPieChart e a seção de evolução temporal (WoundEvolutionSection), permitindo comparar coloração entre capturas do mesmo paciente.
Função: analyze_wound_colors(image_rgb, mask_prob).
Passo 1 — Alinhamento e binarização permissiva
\nmask_aligned = align_mask_to_image(image, mask, "analyze_wound_colors")\nbinary = (mask_aligned > 0.20).astype(uint8) # threshold baixo: incluir bordas difusas\nA análise só é chamada após validate_wound_presence(), então o threshold de 0.20 (vs 0.40 da geometria) é intencional: captura toda a região provável de ferimento, incluindo halos de baixa confiança na borda.
Passo 2 — Limpeza morfológica
\nMORPH_CLOSE(kernel 3×3, 1 iter)\nMORPH_OPEN(kernel 3×3, 1 iter)\n→ largest connected component\nPasso 3 — Máscara de borda
\nRemove 1% das margens da imagem para evitar contaminação por pele circundante ou artefatos de borda:
\nmargin_h = max(1, int(h * 0.01))\nmargin_w = max(1, int(w * 0.01))\nedge_mask[0:margin_h, :] = 0\nedge_mask[h-margin_h:, :] = 0\n# idem para colunas\nbinary = binary * edge_mask\nPasso 4 — Fallback
\nSe wound_pixels == 0 após filtros, reutiliza mask > 0.15 sem máscara de borda, evita retorno zerado em feridas pequenas ou próximas à borda do frame.
Conversão para HSV OpenCV:
\nimage_hsv = cv2.cvtColor(image_rgb, cv2.COLOR_RGB2HSV)\n# H ∈ [0, 179], S ∈ [0, 255], V ∈ [0, 255]\n# Normalização: h/179, s/255, v/255\nPara cada pixel (r,g,b) e (h,s,v) dentro da ROI:
intensity = (r + g + b) / 3\nmax_rgb = max(r, g, b)\nmin_rgb = min(r, g, b)\nOrdem de decisão (first-match wins — evita ambiguidade):
\nPreto → Branco → Roxo → Vermelho → Amarelo → Outros
Preto (necrose)
\nif v < 0.12 or (intensity < 0.15 and max_rgb < 0.2):\n → preto\nelif v < 0.18 and intensity < 0.20 and s < 0.25:\n → preto\n\nPrioridade máxima: sombras profundas e tecido necrótico têm valor HSV baixo.
\nBranco (isquêmico / biofilme)
\nelif s < 0.12 and v > 0.65:\n → branco\nelif s < 0.18 and v > 0.75 and max_rgb > 0.7:\n → branco\nelif s < 0.20 and v > 0.70 and |r-g| < 0.1 and |g-b| < 0.1:\n → branco # tons acinzentados claros\nBaixa saturação + alto valor = tecido pálido ou esbranquiçado.
\nRoxo (hematoma)\nRegras HSV e RGB combinadas:
\nelif 0.68 <= h <= 0.92 and s > 0.25 and v > 0.2:\n → roxo\nelif r > 0.35 and b > 0.35 and g < 0.35 and s > 0.18:\n → roxo # R e B dominantes, G suprimido\nVermelho (granulação)
\nelif (h < 0.04 or h > 0.96) and s > 0.35 and v > 0.25:\n → vermelho # matiz no extremo do círculo H (vermelho puro)\nelif r > 0.55 and r > g*1.25 and r > b*1.25 and s > 0.25:\n → vermelho # dominância de R no RGB\nelif r > 0.50 and r > g*1.2 and s > 0.30 and 0.2 < v < 0.5:\n → vermelho # granulação mais escura\nAmarelo (esfacelo)
\nelif 0.12 <= h <= 0.28 and s > 0.35 and v > 0.3:\n → amarelo\nelif r > 0.45 and g > 0.45 and b < 0.35 and s > 0.25:\n → amarelo # R+G altos, B baixo\nelif 0.28 <= h <= 0.40 and s > 0.30 and g > r and g > b:\n → amarelo # amarelo-esverdeado (infecção)\nelif 0.10 <= h <= 0.25 and s > 0.25 and 0.25 < v < 0.55:\n → amarelo # esfacelo âmbar/escuro\nOutros\nPixels que não satisfazem nenhuma regra acima.
\ntotal = len(wound_region) # pixels na ROI filtrada\ncolor_percentages = {\n 'vermelho': (red_count / total) * 100.0,\n 'amarelo': (yellow_count / total) * 100.0,\n 'preto': (black_count / total) * 100.0,\n 'roxo': (purple_count / total) * 100.0,\n 'branco': (white_count / total) * 100.0,\n 'outros': (other_count / total) * 100.0,\n}\n# Σ ≈ 100%\nIluminação domina crominância. Flash direto, sombra e pele circundante alteram (h,s,v) de forma não linear. O código detecta alta variação (std(RGB) > 40) e loga aviso, mas ainda não aplica correção adaptativa de thresholds — ponto de melhoria.
Segmentação ≠ coloração. Um pixel classificado como vermelho pode ser pele saudável se a máscara vazou. A máscara de borda (1%) e o largest CC mitigam, mas não eliminam o problema.
\nRule-based vs ML. Escolhi regras explícitas porque:
\nO custo: sensibilidade a white balance da câmera e calibração de cor do dispositivo. Um classificador treinado em LAB normalizado ou um modelo multi-classe por patch seria o próximo passo natural.
\nDual color space é necessário. HSV isola matiz (útil para vermelho/amarelo/roxo), mas falha em tons acromáticos (preto/branco) — daí as regras RGB complementares com dominância de canal.
\nThreshold de máscara diferente da geometria. Geometria usa binarização conservadora (0.40 + CC strict); coloração usa 0.20 permissivo. Aprendi que otimizar uma única máscara para ambos os fins é subótimo.
\nSem pixels_per_cm, área em px² não tem unidade clínica. Implementei duas fontes:
Dictionary: DICT_4X4_50
\nMarker ID: 0 (estrito)
\nSize: 2.0 cm (lado físico)
\nPipeline de detecção:
\ncv2.aruco.ArucoDetector (compatível com API legada detectMarkers)marker_id == 0; se múltiplos, seleciona o de maior perímetropixels_per_cm = mean(side_lengths_px) / marker_size_cmCorreção de perspectiva (opcional, ARUCO_APPLY_PERSPECTIVE_CORRECTION=true):
src = corners[4×2] (quadrilátero detectado)
side = max(edge) (lado em px)
dst = [[0,0], [side,0], [side,side], [0,side]]
H = cv2.getPerspectiveTransform(src, dst)
rectified = cv2.warpPerspective(image, H, (side, side))
mask' = cv2.warpPerspective(mask, H, ..., INTER_NEAREST)
Homografia planar assume superfície do marcador (e da ferida) aproximadamente coplanar.\nViolação → erro sistemático em área.
\nErros tipados:
\nmarker_not_detectedinvalid_marker (ID errado)calibration_failed (marcador muito pequeno, < ~24 px de lado)Retry inteligente: se ArUco falha na imagem inteira, re-detecta usando preview binário da máscara como ROI hint.
\nComo alternativa, implementei detecção de régua clínica com CV clássica:
\naspect_ratio > 4.0 (corpo alongado)minAreaRect → eixo principalpixels_per_cm = median(Δx_entre_picos) / RULER_CM_PER_MAJOR_TICKFoi fascinante ver que não precisa de deep learning para tudo. Análise de sinais 1D sobre contornos resolve um problema real com interpretabilidade e baixo custo computacional.
\nConfiança: CV do espaçamento entre picos + número de ticks + aspect ratio.
\nSe ALLOW_ASSUMED_FOV_FALLBACK=true e calibração falha, usa default_assumed_calibration(image_side_px) — escala heurística baseada no FOV. Não é escala clínica; flag calibration.is_clinical_scale() distingue.
Aprendi que ArUco é elegante na teoria e exigente na prática: o marcador precisa estar visível, plano, bem iluminado e com tamanho mínimo em pixels. Por isso o sistema retorna erros específicos (marker_not_detected, invalid_marker, calibration_failed) em vez de falhar silenciosamente.
\nCom a máscara binária e a calibração, extraio métricas clínicas:
\nboundingRect para formas irregulares.minAreaRect e Feret diameter no convex hull.Entrada: contorno C = {(x_i, y_i)}, calibração {pixel_to_cm, confidence}.
area_px = cv2.contourArea(C)\n\nperimeter_px = cv2.arcLength(C, closed=True)\nCentro: μ = mean(C)
Matriz de covariância: Σ = cov(C - μ)
Decomposição: Σ = V Λ Vᵀ via np.linalg.eigh
Autovetor v₁ (maior autovalor) = eixo principal:
proj_major = (C - μ) · v₁\n\nmajor_len = max(proj_major) - min(proj_major)\n\nproj_minor = (C - μ) · v₂\n\nminor_len = max(proj_minor) - min(proj_minor)\n\nangle_deg = atan2(v₁_y, v₁_x) · 180/π\nminAreaRect(C) → (rect_major, rect_minor, rect_angle)(feret_max, feret_min)Dimensão final:
\nwidth_px = median(pca_major, rect_major)\n\nheight_px = median(pca_minor, rect_minor)\nMotivação: cv2.boundingRect superestima feridas alongadas e rotacionadas. PCA captura orientação; mediana entre PCA e minAreaRect reduz sensibilidade a outliers no contorno.
area_cm² = area_px × pixel_to_cm²\n\nperimeter_cm = perimeter_px × pixel_to_cm\n\nwidth_cm = width_px × pixel_to_cm\n\nheight_cm = height_px × pixel_to_cm\n\ndiameter_cm = max(width_cm, height_cm)\ngeometry_confidence = min(calibration_confidence, mask_geometry_confidence)
Checks de plausibilidade (GEOMETRY_REQUIRE_VALID=true):
Falha → InvalidGeometryError.
O pipeline retorna erros estruturados (HTTP 422) com message (frontend) e message_technical:
| Exception | \nCódigo | \nTrigger | \n
|---|---|---|
WoundNotDetectedError | \nno_wound_detected | \nprob_max baixo, área @ 0.5 < threshold | \n
MarkerNotDetectedError | \nmarker_not_detected | \nArUco ausente, ARUCO_REQUIRED=true | \n
InvalidMarkerError | \ninvalid_marker | \nID ≠ 0 | \n
CalibrationFailedError | \ncalibration_failed | \nMarcador inválido / escala não clínica | \n
InvalidSegmentationError | \ninvalid_segmentation | \nCC analysis falhou em todos os níveis | \n
GeometryExtractionError | \ngeometry_extraction_failed | \nContorno < 5 pontos | \n
InvalidGeometryError | \ninvalid_geometry | \nValidação geométrica falhou | \n
O sistema possui um modo avançado de observabilidade para facilitar a inspeção de toda a pipeline de segmentação e análise de cores. Quando DEBUG_SEGMENTATION=true, são aplicadas configurações mais permissivas para facilitar a identificação de problemas durante o processamento:
min_solidity = 0.08max_aspect_ratio = 20GEOMETRY_MIN_CONFIDENCE = 0.20Para cada requisição é criado o diretório debug_outputs/{request_id}/, contendo todos os artefatos intermediários da pipeline:
01_original.png02_......09_overlay.pngmeta.jsonO arquivo meta.json reúne informações detalhadas do processamento, incluindo:
Além disso, a resposta da API passa a incluir o campo segmentation_debug, contendo informações detalhadas para auxiliar na investigação de falhas.
Cada requisição também propaga um ImagePipelineContext, que registra automaticamente as dimensões produzidas em cada etapa da pipeline (shape_log), permitindo identificar rapidamente desalinhamentos entre a imagem original, a inferência da U-Net e a máscara final.
shape_logoriginal_loaded: shape=(3024, 4032, 3)\nworking_capped: shape=(1152, 1536, 3)\npreprocessed_mobile: shape=(1152, 1536, 3)\ninference_letterboxed: shape=(512, 512, 3)\npredicted_mask_inference: shape=(512, 512)\nmask_working_prob: shape=(1152, 1536)\nEsses registros são fundamentais para diagnosticar problemas como diferenças de escala, padding incorreto, redimensionamentos inadequados e desalinhamentos entre a máscara segmentada e a imagem original.
\nA etapa de análise de cores também possui observabilidade dedicada. Durante a execução são registrados:
\nExemplo:
\n🎨 [ColorAnalysis] Pixels analisados: 4821\n🎨 [ColorAnalysis] Color counts - Red: 2104, Yellow: 891, Black: 312, ...\n🎨 [ColorAnalysis] Final percentages:\n{\n 'vermelho': 43.6,\n 'amarelo': 18.5,\n ...\n}\nEsses logs permitem validar tanto a qualidade da segmentação quanto a consistência da classificação cromática, tornando o processo de depuração significativamente mais eficiente.
\nCobertura unitária em:
\ntest_aruco_detection.py — detecção, filtro de ID, cálculo de escalatest_ruler_detection.py — picos periódicos, aspect ratiotest_measurement_geometry.py — PCA, Feret, conversão cmtest_segmentation_postprocess.py — threshold sweep, CC fallbacktest_pipeline_validation.py — presença de ferida, erros tipados1. Domain shift mobile >> ganho de arquitetura
\nVal Dice/IoU em dataset limpo não prediz comportamento em fotos 12 MP com flash, JPEG agressivo e glare. O pipeline de inferência (CLAHE, threshold sweep, CC fallback) compensa mais do que trocar encoder de B3 para B4.
\n2. Threshold é parâmetro de produção, não de treino
\nO sweep [0.35…0.55] é configurável via env. Diferentes dispositivos/câmeras exigem calibração empírica do threshold sem retreinar.
3. DL + CV clássica são complementares
\n| Tarefa | \nAbordagem | \n
|---|---|
| Segmentação semântica | \nU-Net (DL) | \n
| Pré-processamento | \nCLAHE, unsharp (CV clássica) | \n
| Binarização robusta | \nThreshold sweep + morfologia + CC | \n
| Escala métrica | \nArUco / régua (CV clássica) | \n
| Dimensões clínicas | \nPCA + minAreaRect (álgebra linear) | \n
| Correção de perspectiva | \nHomografia (projective geometry) | \n
4. Propagação de coordenadas é a fonte #1 de bugs
\nLetterbox → inferência → unletterbox → homografia (opcional) → overlay. Cada transformação precisa de metadados reversíveis. assert_image_mask_aligned() valida shape/dtype antes de geometria.
5. Fail-fast com diagnóstico
\nRetornar prob_max=0.12 em WoundNotDetectedError é mais útil que retornar máscara vazia silenciosamente. Permite tuning de threshold e detecção de model drift em produção.
6. Export ≠ treino
\nTorchScript trace congela o grafo para (1,3,512,512). Qualquer mudança de input size ou normalização exige re-export. ONNX com dynamic_axes no batch é mais flexível para classificação.