jhonny-editor/code/docs/levantamento-ferramentas-analise-visual-local.md

# Levantamento de ferramentas locais para análise visual

Data: 2026-09-08  
Escopo: escolher a base para implementar um `ProviderDeAnaliseVisual` real no `engine/scanner`.

## Recomendação executiva

Adotar uma arquitetura em camadas:

1. **Apple Vision + Core ML** como provider principal para macOS: OCR, rostos, pessoas, poses, códigos, classificação, qualidade e similaridade visual.
2. **PySceneDetect** para detectar cortes e delimitar cenas no arquivo de origem.
3. **ONNX Runtime com CoreML Execution Provider** como runtime de modelos customizados, mantendo a possibilidade de usar os mesmos modelos em outras plataformas.
4. **MediaPipe Tasks** como alternativa especializada para pose, mãos, rosto e rastreamento quando o resultado do Vision não for suficiente.
5. **Modelo multimodal local** somente como uma etapa semântica opcional, posterior às análises determinísticas; não deve ser a fonte primária de eventos temporais.

Essa composição aproveita o Apple Silicon sem enviar mídia para a nuvem, separa fatos observáveis de interpretação e permite evoluir os modelos sem alterar o contrato do Scanner.

## Critérios usados

- execução local e offline;
- integração com macOS/Apple Silicon;
- possibilidade de obter intervalos temporais e confiança;
- suporte a frames, vídeo e processamento em lote;
- integração com Python ou bridge nativa pequeno;
- licença adequada para produto comercial;
- maturidade e manutenção do projeto;
- adequação ao nosso domínio: cenas, objetos, pessoas, OCR, qualidade e possíveis retakes.

## Candidatos

### 1. Apple Vision + Core ML — recomendação principal

O Vision oferece APIs pré-treinadas para análise de imagens e vídeo, incluindo texto, códigos, rostos, pessoas, poses, classificação, qualidade e similaridade visual. O processamento ocorre no dispositivo. Core ML executa modelos usando CPU, GPU e Neural Engine, também sem exigir conexão de rede.

**Pontos fortes**

- melhor alinhamento com o ambiente macOS existente;
- privacidade e execução local;
- bons blocos prontos para OCR, faces, pessoas, poses e qualidade;
- suporte nativo a tracking entre frames;
- possibilidade de usar modelos próprios convertidos para Core ML;
- sem dependência de um servidor Python pesado.

**Limitações**

- a API é Swift/Objective-C, não Python;
- será necessário um processo auxiliar Swift ou uma pequena bridge JSON;
- não substitui um detector geral de objetos com classes customizadas;
- os resultados são observações de visão, não uma noção editorial pronta de “take bom” ou “retake”.

**Uso recomendado no Scanner**

- `ProviderDeAnaliseVisualApple` executando um helper Swift;
- entrada: arquivo + lista de timestamps;
- saída: observações por frame, cada uma com `timestamp`, tipo, bounding box, label, confiança e provider;
- usar `VNGenerateImageFeaturePrintRequest`/similaridade visual para apoiar comparação de takes;
- usar análise de qualidade para foco, exposição e problemas técnicos quando disponível.

Fontes: [Apple Vision](https://developer.apple.com/documentation/vision), [detecção de objetos no Vision](https://developer.apple.com/documentation/vision/detecting_objects_in_still_images), [reconhecimento de texto](https://developer.apple.com/documentation/vision/recognizing-text-in-images) e [Apple Core ML](https://developer.apple.com/documentation/coreml).

### 2. PySceneDetect — recomendação para cortes de cena

Biblioteca Python/BSD-3 para detectar mudanças de cena. Possui `ContentDetector`, `AdaptiveDetector` e `ThresholdDetector`, retorna pares de início/fim e oferece integração com FFmpeg.

**Pontos fortes**

- integração direta com o engine Python;
- contrato temporal já próximo do nosso `Cena`;
- simples de testar com arquivos reais e fixtures;
- licença BSD-3-Clause;
- mais apropriado para “onde a cena muda” do que um VLM.

**Limitações**

- detecta transições visuais, não entende o conteúdo sem um segundo modelo;
- pode gerar falsos positivos com movimento de câmera, flashes e mudanças de iluminação;
- deve operar sobre o arquivo de origem e depois ser projetado para os intervalos da timeline.

Fonte: [repositório oficial PySceneDetect](https://github.com/Breakthrough/PySceneDetect).

### 3. ONNX Runtime + CoreML Execution Provider — recomendação como runtime extensível

ONNX Runtime fornece API Python e permite executar modelos ONNX com `CoreMLExecutionProvider`. As wheels oficiais para macOS incluem o provider Core ML; há opções para CPU, GPU e Neural Engine quando suportadas pelo modelo e pelo dispositivo.

**Pontos fortes**

- desacopla o Scanner do framework de treinamento;
- permite plugar modelos de detecção, classificação, pose ou embeddings;
- mantém uma rota futura para Windows/Linux por outros execution providers;
- cacheia modelos compilados do Core ML;
- API Python direta.

**Limitações**

- a compatibilidade depende dos operadores e do formato do modelo;
- precisamos controlar conversão, pré-processamento, pós-processamento e versionamento;
- usar Core ML não garante que 100% do grafo rode na Neural Engine.

**Uso recomendado no Scanner**

- runtime para modelos licenciados de forma compatível com o produto;
- um `ModeloVisualONNX` interno com adaptadores para detecção/classificação;
- fallback CPU explícito e registro do device usado no resultado.

Fonte: [ONNX Runtime — CoreML Execution Provider](https://onnxruntime.ai/docs/execution-providers/CoreML-ExecutionProvider.html).

### 4. MediaPipe Tasks — alternativa especializada

MediaPipe oferece tarefas de visão com APIs para Python e modelos prontos, incluindo detecção de objetos, classificação, segmentação, rosto, mãos, pose e holístico.

**Quando usar**

- pose corporal, mãos, gestos e landmarks;
- tracking de pessoas em trechos curtos;
- quando quisermos manter o mesmo componente em macOS, Linux e Windows.

**Limitações**

- exige escolher e distribuir arquivos de modelo;
- a cobertura e o formato de resultados são diferentes do Vision;
- não deve ser adicionado apenas por sobreposição: primeiro precisamos de um caso que o Vision não resolva.

Fonte: [Google AI Edge — MediaPipe Object Detector para Python](https://ai.google.dev/edge/mediapipe/solutions/vision/object_detector/python).

### 5. Ultralytics YOLO — tecnicamente forte, com risco de licença

Ultralytics oferece detecção, segmentação, pose, classificação e tracking em Python, com modelos pré-treinados e treinamento customizado.

**Vantagens técnicas**

- integração rápida;
- ecossistema amplo;
- bom caminho para objetos específicos do nosso domínio;
- suporta tracking e modelos customizados.

**Risco decisivo**

O código e os artefatos são apresentados sob AGPL-3.0, e a própria documentação indica licença Enterprise para desenvolvimento e produção que não possam cumprir as obrigações da AGPL. Não devemos incorporar Ultralytics ao produto sem uma decisão jurídica/licenciamento explícita.

**Decisão**

Usar apenas em benchmark/protótipo isolado até resolver a licença. Para produção, preferir modelos e runtimes com licença compatível ou adquirir a licença Enterprise.

Fontes: [documentação oficial Ultralytics](https://github.com/ultralytics/ultralytics), [licença e opções comerciais](https://github.com/ultralytics/ultralytics/blob/main/docs/en/index.md).

### 6. OpenCV — fundação de processamento, não provider semântico

OpenCV é útil para decodificação de frames, resize, cor, blur, histograma, métricas técnicas, comparação de imagens e pré/pós-processamento. Também pode executar modelos via DNN, mas não deve ser tratado sozinho como a solução de reconhecimento semântico.

**Uso recomendado**

- extração/amostragem de frames;
- foco, exposição, contraste, ruído e estabilidade;
- diferenças entre frames;
- suporte aos providers Vision, ONNX e MediaPipe.

Fonte: [licença oficial OpenCV](https://opencv.org/license/).

## O que não recomendar como núcleo

Um VLM local pode produzir descrições como “pessoa falando em uma sala”, mas é menos determinístico, mais caro em memória e menos adequado para localizar cortes com precisão. Ele pode entrar depois para gerar descrição semântica de cenas já delimitadas, nunca substituir `PySceneDetect`, Vision ou um detector temporal.

Também não devemos começar pelo YOLO/Ultralytics como dependência central antes de resolver AGPL/licença comercial.

## Matriz resumida

| Ferramenta | Melhor uso | Python direto | Apple Silicon | Offline | Licença/risco | Decisão |
|---|---|---:|---:|---:|---|---|
| Vision | OCR, faces, pessoas, pose, qualidade, similaridade | Não | Excelente | Sim | Framework Apple | Adotar |
| Core ML | Modelos próprios no hardware Apple | Via bridge/runtime | Excelente | Sim | Framework Apple | Adotar |
| PySceneDetect | Cortes e intervalos de cena | Sim | Boa | Sim | BSD-3-Clause | Adotar |
| ONNX Runtime + CoreML EP | Runtime de modelos customizados | Sim | Excelente | Sim | MIT | Adotar como extensão |
| MediaPipe Tasks | Pose, mãos, rosto, holístico | Sim | Boa | Sim | Apache-2.0 no framework; conferir cada modelo | Avaliar por caso |
| OpenCV | Frames e métricas técnicas | Sim | Boa | Sim | Apache-2.0 | Adotar como base auxiliar |
| Ultralytics YOLO | Objetos/pose/tracking | Sim | Boa | Sim | AGPL ou Enterprise | Protótipo somente até decisão |

## Desenho proposto para o nosso código

```text
Clipe/arquivo
    ↓
ExtratorDeQuadros (FFmpeg/OpenCV)
    ↓
ProviderDeAnaliseVisual
    ├── AppleVisionProvider
    ├── PySceneDetectProvider
    ├── ONNXCoreMLProvider (opcional)
    └── MediaPipeProvider (opcional)
    ↓
EvidenciaVisual(timestamp, intervalo, tipo, valor, confianca, provider)
    ↓
ContextoDeAnalise.caracteristicas_visuais / cenas / eventos
```

O contrato atual `ProviderDeAnaliseVisual.analisar(clipe, quadros)` é suficiente para o primeiro passo, mas a saída precisa evoluir de um `dict` livre para evidências temporais. A unidade mínima deveria conter:

- `tipo`: `ocr`, `pessoa`, `objeto`, `pose`, `qualidade`, `similaridade` ou `mudanca_de_cena`;
- `inicio` e `fim` ou `timestamp`;
- `valor` estruturado;
- `confianca` quando fornecida pelo modelo;
- `provider` e `modelo`;
- versão do modelo e hash opcional;
- referência ao arquivo/frame analisado.

## Ordem recomendada de implementação

1. Criar `ExtracaoDeQuadros` usando FFmpeg/OpenCV, com amostragem por intervalo e cache por hash do arquivo.
2. Implementar um helper Swift pequeno para Apple Vision e um `ProviderDeAnaliseVisualApple` Python que troca JSON por stdin/stdout.
3. Adicionar PySceneDetect como etapa própria de detecção de cenas.
4. Criar testes com fixture curta para OCR, presença de pessoa, qualidade e mudança de cena.
5. Medir tempo, memória, cobertura e estabilidade dos resultados em Apple Silicon.
6. Só depois adicionar ONNX/MediaPipe para lacunas concretas.
7. Avaliar um VLM local apenas para descrição semântica de cenas já delimitadas.

## Conclusão

Para o produto atual, a melhor escolha não é uma única biblioteca. É **Vision/Core ML + PySceneDetect + OpenCV**, com **ONNX Runtime/CoreML** como ponto de extensão. Essa combinação cobre a maior parte do Scanner com processamento local, preserva a privacidade e evita amarrar o domínio a uma biblioteca de modelos com licença problemática.