core/models library

Biblioteca de utilitários para carregar e gerenciar modelos de visão computacional usando ExecuTorch.

Esta biblioteca fornece abstrações e contratos claros para trabalhar com três perfis de modelos comuns: detecção de objetos, segmentação de imagens e classificação de imagens. Apresenta propriedades reutilizáveis (caminho do modelo, dimensões de entrada, rótulos, parâmetros de pré/pós-processamento) e descreve o formato esperado de entrada/saída para facilitar integração e testes.

Uso (exemplo ilustrativo)

// Exemplo ilustrativo — adapte à API concreta do ExecuTorch no seu projeto.
final model = DetectionModel(modelPath: 'assets/models/detector.pt', inputSize: Size(640,640));
final results = await model.predict(image); // retornará lista de detecções

Classes fornecidas

• DetectionModel

  • Propósito: detectar objetos em imagens e retornar bounding boxes, scores e rótulos.
  • Entrada: imagem (ex.: Uint8List, Image, ou outra representação suportada), dimensões de entrada (width × height) para redimensionamento/preproc.
  • Saída prevista: lista de detecções com {box: Rect, score: double, label: String, classId: int}.
  • Configurações típicas: threshold de confiança, NMS (non-maximum suppression), limite máximo de detecções, formato de coordenadas (normalizado ou pixels).

• SegmentModel

  • Propósito: gerar máscaras de segmentação por objeto ou por classe para uma imagem.
  • Saída prevista: máscaras binárias ou mapas de probabilidade (por-pixel), opcionalmente associadas a rótulos e scores; formatos retornados podem incluir arrays de floats, bitmaps ou imagens RGBA conforme configuração.
  • Observações: cuidado com alinhamento entre máscara e imagem original (resize / pad).

• ClassifyModel

  • Propósito: classificar imagens e retornar uma lista ordenada de rótulos com scores.
  • Saída prevista: lista de {label: String, score: double, classId: int}, tipicamente ordenada por probabilidade decrescente.
  • Observações: suporte a top-k, normalização de scores (softmax) e transformação de entrada.

Propriedades comuns e contratos

• modelPath: caminho para o arquivo do modelo (assets, pacote, caminho absoluto).
• inputSize: dimensões (width, height) esperadas pelo modelo; o loader deve aplicar redimensionamento e, se necessário, padding para manter razão de aspecto.
• labelsPath: arquivo de rótulos (um por linha). Se ausente, as classes ficam indexadas por inteiro.
• normalization (mean / std): parâmetros para normalizar pixels antes da inferência.
• batchSize: quando suportado pelo backend, permita inferência em lote.
• Formatos de modelo: dependem do backend ExecuTorch utilizado (p. ex. TorchScript, ONNX, TFLite).

Comportamento, erros e garantias

• Validação: carregadores devem lançar exceções claras para erros como arquivo não encontrado, formato inválido ou incompatibilidade de dimensão.
• Performance: carregamento de modelo é custoso — reutilize instâncias carregadas e evite recarregar em loop; ofereça inicialização assíncrona (async) no app.
• Thread-safety: documente se instâncias são seguras para uso concorrente; caso contrário, exponha factories/locks para gerenciar acesso.
• Precisão dos resultados: resultados pós-processados (NMS, threshold, mapeamento de rótulos) devem ser reproduzíveis e configuráveis via parâmetros públicos.

Boas práticas recomendadas

• Documente explicitamente formatos de entrada (RGB vs BGR, ordem de canais, range 0..1 vs 0..255).
• Forneça utilitários de pré/processamento reutilizáveis (resize + pad + normalize).
• Exponha parâmetros de pós-processamento (NMS, score threshold, top-k) na API pública.
• Inclua exemplos e testes de inferência com modelos toy para garantir compatibilidade entre versões.

Exemplo de contrato de saída (detecção)

/// Representação de uma detecção retornada por DetectionModel
class Detection {
  final Rect box;       // Caixa em coordenadas da imagem original
  final double score;   // Confiança (0.0 - 1.0)
  final String label;   // Rótulo legível
  final int classId;    // ID numérico da classe
}

Observações finais

• Documente no README do pacote procedimentos de conversão de modelos, formatos suportados, e exemplos completos de pré/pós-processamento aplicáveis ao pipeline ExecuTorch.
• Sempre forneça testes de integração que executem inferência end-to-end com pequenos modelos para detectar regressões de I/O, dimensionamento e mapeamento de rótulos. Biblioteca para carregar e gerenciar modelos de visão computacional usando ExecuTorch. Define classes para modelos de detecção, segmentação e classificação. Propriedades comuns incluem caminho do modelo, dimensões de entrada e rótulos. Módulos Definidos:
  • DetectionModel: Classe para modelos de detecção de objetos.
  • SegmentModel: Classe para modelos de segmentação de imagens.
  • ClassifyModel: Classe para modelos de classificação de imagens.