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, detecção de objetos no Vision, reconhecimento de texto e Apple Core ML.

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.

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.

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.

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, licença e opções comerciais.

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.

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

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.