ovicore 0.1.0__py3-none-any.whl

ovicore/__init__.py

@@ -0,0 +1,20 @@
+"""
+Núcleo de avaliação padronizada para comparação de frameworks de detecção
+de objetos.
+
+Projeto UFSM-Fiocruz: detecção de ovos de Aedes aegypti em ovitrampas.
+"""
+
+__version__ = "0.1.0"
+
+from ovicore.metrics import avaliar, compute_iou, compute_metrics
+from ovicore.io import (
+    gravar_predicoes, carregar_predicoes, montar_metadata,
+    validar_contrato, padronizar_labels_para_int,
+)
+
+__all__ = [
+    "avaliar", "compute_iou", "compute_metrics",
+    "gravar_predicoes", "carregar_predicoes", "montar_metadata",
+    "validar_contrato", "padronizar_labels_para_int",
+]

ovicore/anotacoes.py

@@ -0,0 +1,51 @@
+"""
+Leitura da verdade-terreno a partir de um JSON no formato COCO.
+
+Devolve as caixas já em [x1, y1, x2, y2], prontas para metrics.avaliar e
+io.montar_predicoes. Só lê: não altera o arquivo.
+"""
+
+import json
+
+from ovicore.contracts import BBox
+
+
+def ler_anotacoes_coco(
+    caminho_json: str, deslocamento_classe: int = 0
+) -> dict[str, tuple[list[list[float]], list[int]]]:
+    """
+    Devolve {file_name: (caixas, classes)}, com uma entrada para cada
+    imagem do JSON, inclusive as que não têm anotação (listas vazias).
+
+    As caixas saem em xyxy via BBox.from_coco: [x, y, x + w, y + h]. Ver E0.
+    A classe é o category_id, como int, somado a deslocamento_classe.
+
+    pred_labels e true_labels precisam estar no mesmo espaço de ids. Use
+    deslocamento_classe só se os ids das predições forem diferentes dos do
+    JSON. Confira antes: no Faster R-CNN de referência não há deslocamento.
+    """
+    with open(caminho_json, encoding="utf-8") as f:
+        coco = json.load(f)
+
+    for campo in ("images", "annotations"):
+        if campo not in coco:
+            raise ValueError(f"{caminho_json} não é COCO: falta o campo '{campo}'")
+
+    por_imagem = {}
+    for ann in coco["annotations"]:
+        faltando = [c for c in ("image_id", "bbox", "category_id") if c not in ann]
+        if faltando:
+            raise ValueError(f"anotação {ann.get('id')} sem os campos {faltando}")
+        caixa = BBox.from_coco(ann["bbox"])
+        classe = int(ann["category_id"]) + deslocamento_classe
+        caixas, classes = por_imagem.setdefault(ann["image_id"], ([], []))
+        caixas.append([caixa.x1, caixa.y1, caixa.x2, caixa.y2])
+        classes.append(classe)
+
+    resultado = {}
+    for img in coco["images"]:
+        faltando = [c for c in ("id", "file_name") if c not in img]
+        if faltando:
+            raise ValueError(f"imagem {img} sem os campos {faltando}")
+        resultado[img["file_name"]] = por_imagem.get(img["id"], ([], []))
+    return resultado

ovicore/backends/__init__.py

@@ -0,0 +1 @@
+"""Adaptadores concretos de DetectorBackend, um por framework."""

ovicore/backends/detectron2_backend.py

@@ -0,0 +1,126 @@
+"""
+Backend do Detectron2. Estão prontos extrair_budget e gerar_config; os
+outros métodos dependem de rodar com o framework instalado.
+"""
+
+import json
+
+from ovicore.contracts import DetectorBackend, TrainingBudget, BBoxFormat
+
+
+class Detectron2Backend(DetectorBackend):
+
+    def __init__(self, batch_size_treino: int, optimizer: str = "SGD"):
+        """
+        batch_size_treino: o batch do treino (ex.: 8), usado para converter
+        iterações em épocas. Não fica salvo no metrics.json.
+
+        optimizer: suposição, o padrão do Detectron2. O metrics.json não
+        registra o otimizador usado.
+        """
+        self._batch_size_treino = batch_size_treino
+        self._optimizer = optimizer
+
+    @property
+    def nome(self) -> str:
+        return "detectron2"
+
+    @property
+    def formato_anotacao_esperado(self) -> BBoxFormat:
+        return BBoxFormat.XYWH
+
+    @property
+    def score_range_observado(self) -> tuple:
+        # Faixa observada em execução real, fold-01-416 (ver E5).
+        return (0.0, 0.995)
+
+    def extrair_budget(self, caminho_metrics_json: str) -> TrainingBudget:
+        """
+        Lê o orçamento do metrics.json gerado pelo Detectron2, não de
+        configuração externa. Ver E6.
+
+        O arquivo é JSON Lines: uma linha por avaliação periódica, cada uma
+        com a iteração e a learning rate do momento.
+        """
+        linhas = []
+        with open(caminho_metrics_json) as f:
+            for linha in f:
+                linha = linha.strip()
+                if linha:
+                    linhas.append(json.loads(linha))
+
+        if not linhas:
+            raise ValueError(f"{caminho_metrics_json} está vazio")
+
+        # O campo "iteration" conta a partir de zero: a última linha de um
+        # treino de 3000 iterações registra 2999.
+        ultima_iteracao = linhas[-1]["iteration"] + 1
+        # A learning rate declarada no arquivo varia com o schedule.
+        # O valor de pico (o maior visto) é o que a configuração pediu.
+        learning_rate = max(l["lr"] for l in linhas if "lr" in l)
+
+        return TrainingBudget(
+            iterations=ultima_iteracao,
+            epochs=None,  # calculado à parte, precisa do tamanho do dataset
+            batch_size=self._batch_size_treino,
+            learning_rate=learning_rate,
+            optimizer=self._optimizer,
+            fonte="metrics.json",
+        )
+
+    def epocas_equivalentes(self, budget: TrainingBudget, tamanho_dataset: int) -> float:
+        """
+        Converte iterações em épocas equivalentes. Ver E7: contar por
+        iteração esconde que os modelos viram o dataset um número de vezes
+        bem diferente.
+
+        O amostrador do Detectron2 é infinito: sorteia lotes sem fechar
+        épocas, então o treino viu iterações × lote imagens. Arredondar os
+        lotes por época para cima (como o notebook do grupo faz para chegar
+        ao MAX_ITER) só coincide quando o dataset é múltiplo do lote: com
+        131 imagens daria 176,5 épocas em vez de 183,2.
+        """
+        return budget.iterations * budget.batch_size / tamanho_dataset
+
+    @staticmethod
+    def gerar_config(arquivo_zoo: str, num_classes: int, destino: str,
+                     mascara: bool = True) -> str:
+        """
+        Grava um config.yaml para inferência a partir do model zoo, com o
+        número de classes do treino. Os zips de modelo do grupo não trazem o
+        config usado no treino.
+
+        Para inferência só pesam a arquitetura e o NUM_CLASSES; lote e
+        solver só afetam o treino. Os datasets ficam vazios para o sahi não
+        tomar os nomes das 80 classes do COCO. Vale para modelos com
+        ROI_HEADS (Faster R-CNN, Mask R-CNN), não para RetinaNet.
+
+        mascara=False desliga a cabeça de máscara do Mask R-CNN. Com máscara,
+        o sahi 0.11.19 monta a caixa a partir do contorno da máscara, em
+        pixels inteiros; sem ela, a caixa vem da cabeça de detecção, em
+        coordenadas decimais, como no Faster R-CNN. Os pesos são os mesmos.
+        """
+        try:
+            from detectron2.config import get_cfg
+            from detectron2.model_zoo import get_config_file
+        except ImportError as e:
+            raise ImportError("gerar_config precisa do detectron2 instalado") from e
+
+        cfg = get_cfg()
+        cfg.merge_from_file(get_config_file(arquivo_zoo))
+        cfg.MODEL.ROI_HEADS.NUM_CLASSES = num_classes
+        cfg.DATASETS.TRAIN = ()
+        cfg.DATASETS.TEST = ()
+        if not mascara:
+            cfg.MODEL.MASK_ON = False
+        with open(destino, "w", encoding="utf-8") as f:
+            f.write(cfg.dump())
+        return destino
+
+    # --- ainda não implementado ---
+
+    def carregar_modelo(self, caminho: str) -> None:
+        raise NotImplementedError("carregar_modelo: próxima etapa")
+
+    def inferir(self, caminho_imagem, slicing, score_threshold):
+        raise NotImplementedError("inferir: próxima etapa")

ovicore/backends/huggingface_backend.py

@@ -0,0 +1,69 @@
+"""
+Backend do HuggingFace (DETR). Só extrair_budget está pronto, lendo o
+orçamento do trainer_state.json que o Trainer grava com save_state().
+"""
+
+import json
+
+from ovicore.contracts import DetectorBackend, TrainingBudget, BBoxFormat
+
+
+class HuggingFaceBackend(DetectorBackend):
+
+    @property
+    def nome(self) -> str:
+        return "huggingface"
+
+    @property
+    def formato_anotacao_esperado(self) -> BBoxFormat:
+        return BBoxFormat.XYWH
+
+    @property
+    def score_range_observado(self) -> tuple:
+        # conditional-detr-resnet-50, fold-01-256, sahi 0.12.6: o sahi usa a
+        # sigmoid do próprio modelo. 0,394 em 07/09/2026, 0,371 no retreino
+        # de 08/11/2026 (ver E10).
+        return (0.0, 0.394)
+
+    def extrair_budget(self, caminho_trainer_state: str,
+                       caminho_parametros: str = None) -> TrainingBudget:
+        """
+        Épocas, passos e lote efetivo vêm do trainer_state.json, o registro
+        do treino que rodou: com auto_find_batch_size o lote só é conhecido
+        ali. A learning rate e o otimizador vêm do parametros_treino.json do
+        notebook de treino, quando informado. Sem ele, a learning rate é a
+        maior registrada no log, que fica um pouco abaixo da pedida porque o
+        log não cai exatamente no pico do warmup.
+        """
+        with open(caminho_trainer_state, encoding="utf-8") as f:
+            estado = json.load(f)
+        if "log_history" not in estado:
+            raise ValueError(f"{caminho_trainer_state} não é um trainer_state.json do Trainer")
+
+        learning_rate, otimizador = None, None
+        if caminho_parametros:
+            with open(caminho_parametros, encoding="utf-8") as f:
+                orcamento = json.load(f)["orcamento"]
+            learning_rate, otimizador = orcamento.get("learning_rate"), orcamento.get("optim")
+        if learning_rate is None:
+            learning_rate = max((l["learning_rate"] for l in estado["log_history"]
+                                 if "learning_rate" in l), default=None)
+
+        return TrainingBudget(
+            epochs=estado.get("num_train_epochs"),
+            iterations=estado.get("global_step"),
+            batch_size=estado.get("train_batch_size"),
+            learning_rate=learning_rate,
+            optimizer=otimizador,
+            # menos passos que o previsto: o treino parou antes do fim
+            early_stopping=estado.get("global_step", 0) < estado.get("max_steps", 0),
+            fonte="trainer_state.json",
+        )
+
+    # --- ainda não implementado ---
+
+    def carregar_modelo(self, caminho: str) -> None:
+        raise NotImplementedError("carregar_modelo: próxima etapa")
+
+    def inferir(self, caminho_imagem, slicing, score_threshold):
+        raise NotImplementedError("inferir: próxima etapa")

ovicore/backends/ultralytics_backend.py

@@ -0,0 +1,85 @@
+"""
+Backend do Ultralytics (YOLO). Só extrair_budget está pronto, lendo o
+orçamento do artefato real em vez de configuração externa. Ver E6.
+"""
+
+from ovicore.contracts import DetectorBackend, TrainingBudget, BBoxFormat
+
+
+class UltralyticsBackend(DetectorBackend):
+
+    @property
+    def nome(self) -> str:
+        return "ultralytics"
+
+    @property
+    def formato_anotacao_esperado(self) -> BBoxFormat:
+        return BBoxFormat.CXCYWH_NORM
+
+    @property
+    def score_range_observado(self) -> tuple:
+        # Faixa observada em execução real, fold-01-416, yolov8n (ver E5).
+        return (0.0, 0.907)
+
+    def extrair_budget(self, caminho_checkpoint: str) -> TrainingBudget:
+        """
+        Lê o orçamento direto do checkpoint .pt. O Ultralytics guarda os
+        hiperparâmetros em 'train_args', dentro do próprio arquivo, sem
+        precisar de metrics.json nem do batch_size_treino do Detectron2.
+        """
+        # Assimetria: ler este checkpoint exige torch e o pacote ultralytics
+        # instalados (o pickle referencia classes deles); o Detectron2Backend só usa json.
+        import torch
+        ckpt = torch.load(caminho_checkpoint, map_location="cpu", weights_only=False)
+        return self._parse_checkpoint(ckpt)
+
+    @staticmethod
+    def _parse_checkpoint(ckpt: dict) -> TrainingBudget:
+        """Validação + interpretação, sem depender de torch para ser testada."""
+        if "train_args" not in ckpt:
+            raise ValueError(
+                "checkpoint sem 'train_args'. Não é um checkpoint de treino "
+                "do Ultralytics, ou está corrompido."
+            )
+        budget = UltralyticsBackend._budget_from_train_args(ckpt["train_args"])
+        resultados = ckpt.get("train_results") or {}
+        if resultados.get("epoch"):
+            budget.epocas_executadas, budget.melhor_epoca = (
+                UltralyticsBackend._epocas_de_train_results(resultados))
+        return budget
+
+    @staticmethod
+    def _epocas_de_train_results(resultados: dict) -> tuple:
+        """
+        Épocas que de fato rodaram e a época do best.pt, a de maior fitness.
+        O fitness do Ultralytics para detecção é 0,1 × mAP50 + 0,9 × mAP50-95.
+        """
+        epocas = resultados["epoch"]
+        fitness = [0.1 * a + 0.9 * b for a, b in
+                   zip(resultados["metrics/mAP50(B)"], resultados["metrics/mAP50-95(B)"])]
+        melhor = max(range(len(fitness)), key=fitness.__getitem__)
+        return int(max(epocas)), int(epocas[melhor])
+
+    @staticmethod
+    def _budget_from_train_args(args: dict) -> TrainingBudget:
+        """
+        Parte pura da leitura, sem torch nem ultralytics. Separada para que
+        a maioria dos testes rode sem as dependências pesadas.
+        """
+        return TrainingBudget(
+            epochs=args.get("epochs"),
+            iterations=None,  # Ultralytics não conta por iteração, só por época
+            batch_size=args.get("batch"),
+            learning_rate=args.get("lr0"),
+            optimizer=args.get("optimizer"),
+            early_stopping=bool(args.get("patience", 0) > 0),
+            fonte="checkpoint.train_args",
+        )
+
+    # --- ainda não implementado ---
+
+    def carregar_modelo(self, caminho: str) -> None:
+        raise NotImplementedError("carregar_modelo: próxima etapa")
+
+    def inferir(self, caminho_imagem, slicing, score_threshold):
+        raise NotImplementedError("inferir: próxima etapa")

ovicore/contracts.py

@@ -0,0 +1,250 @@
+"""
+Tipos e interfaces do core: como uma caixa é representada, o que descreve
+um dataset e o que cada backend precisa implementar.
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from enum import Enum
+from typing import Optional
+
+
+class BBoxFormat(str, Enum):
+    XYXY = "xyxy"             # [x1, y1, x2, y2], formato interno
+    XYWH = "xywh"             # [x, y, largura, altura], COCO
+    CXCYWH_NORM = "cxcywh_n"  # [cx, cy, w, h] normalizado, YOLO
+
+
+class Granularity(str, Enum):
+    FULL_IMAGE = "full_image"  # imagem inteira, recortada na inferência
+    PRE_TILED = "pre_tiled"    # recortes já salvos em disco
+
+
+@dataclass(frozen=True)
+class BBox:
+    """
+    Caixa no formato interno do core: [x1, y1, x2, y2] em pixels.
+
+    Só aceita float comum do Python. np.float32 quebra a gravação do CSV
+    e int corta as casas decimais, o que distorce a medição em objetos
+    pequenos. Ver docs/EVIDENCIAS.md, E1 e E2.
+    """
+    x1: float
+    y1: float
+    x2: float
+    y2: float
+
+    def __post_init__(self):
+        for nome in ("x1", "y1", "x2", "y2"):
+            if type(getattr(self, nome)) is not float:
+                raise TypeError(
+                    f"BBox.{nome} deve ser float comum, recebeu "
+                    f"{type(getattr(self, nome)).__name__}"
+                )
+        if self.x2 <= self.x1 or self.y2 <= self.y1:
+            raise ValueError(f"caixa inválida: {self}")
+
+    @property
+    def largura(self) -> float:
+        return self.x2 - self.x1
+
+    @property
+    def altura(self) -> float:
+        return self.y2 - self.y1
+
+    @classmethod
+    def from_coco(cls, bbox_xywh) -> "BBox":
+        """Converte de [x, y, largura, altura]."""
+        x, y, w, h = (float(v) for v in bbox_xywh)
+        return cls(x, y, x + w, y + h)
+
+
+@dataclass(frozen=True)
+class Detection:
+    bbox: BBox
+    class_id: int
+    score: float
+
+
+@dataclass(frozen=True)
+class Annotation:
+    bbox: BBox
+    class_id: int
+
+
+@dataclass
+class DatasetSpec:
+    """Descreve um dataset e permite verificar se dois são comparáveis."""
+    nome: str
+    fold: str
+    tile_size: int
+    granularidade: Granularity
+    id2label: dict
+    caminho_imagens: str
+    caminho_anotacoes: str
+    formato_anotacao: BBoxFormat
+    seed_split: Optional[int] = None
+
+    def validar_contra(self, outro: "DatasetSpec") -> list:
+        """Retorna o que impede comparar resultados destes dois datasets."""
+        problemas = []
+        if self.granularidade != outro.granularidade:
+            problemas.append(
+                f"granularidade: {self.granularidade} vs {outro.granularidade}")
+        if self.fold != outro.fold:
+            problemas.append(f"fold: {self.fold} vs {outro.fold}")
+        if self.tile_size != outro.tile_size:
+            problemas.append(f"tile_size: {self.tile_size} vs {outro.tile_size}")
+        if self.id2label != outro.id2label:
+            problemas.append("mapeamento de classes diferente")
+        return problemas
+
+
+@dataclass
+class TrainingBudget:
+    """
+    Como o modelo foi treinado.
+
+    Os valores devem vir do modelo salvo (metrics.json, train_args do
+    checkpoint), não do notebook que o carrega. Ver E6.
+
+    epochs é o máximo configurado. Com parada antecipada, o treino roda
+    menos: epocas_executadas e melhor_epoca (a do modelo salvo) dizem
+    quanto, quando o artefato registra. Ver E11.
+    """
+    epochs: Optional[int] = None
+    iterations: Optional[int] = None
+    batch_size: Optional[int] = None
+    learning_rate: Optional[float] = None
+    optimizer: Optional[str] = None
+    early_stopping: bool = False
+    fonte: str = "desconhecida"
+    epocas_executadas: Optional[int] = None
+    melhor_epoca: Optional[int] = None
+
+    def comparavel_com(self, outro: "TrainingBudget") -> list:
+        problemas = []
+        if self.epochs and outro.epochs and self.epochs != outro.epochs:
+            problemas.append(f"épocas: {self.epochs} vs {outro.epochs}")
+        if (self.learning_rate and outro.learning_rate
+                and self.learning_rate != outro.learning_rate):
+            problemas.append(f"lr: {self.learning_rate} vs {outro.learning_rate}")
+        if (self.batch_size and outro.batch_size
+                and self.batch_size != outro.batch_size):
+            problemas.append(f"batch: {self.batch_size} vs {outro.batch_size}")
+        if self.optimizer != outro.optimizer:
+            problemas.append(f"otimizador: {self.optimizer} vs {outro.optimizer}")
+        return problemas
+
+
+@dataclass
+class SlicingConfig:
+    """Configuração de recorte (SAHI), igual para todos os frameworks."""
+    slice_height: int = 416
+    slice_width: int = 416
+    overlap_ratio: float = 0.25
+    postprocess_type: str = "NMS"
+    postprocess_match_metric: str = "IOU"
+    postprocess_match_threshold: float = 0.45
+    class_agnostic: bool = False
+
+
+class DetectorBackend(ABC):
+    """
+    O que cada framework precisa implementar para entrar no core.
+
+    O core não treina nada. A entrada é uma fonte única em COCO, descrita
+    por DatasetSpec. O que o core padroniza é a saída (list[Detection]).
+    """
+
+    @property
+    @abstractmethod
+    def nome(self) -> str:
+        """detectron2, ultralytics, huggingface"""
+
+    @property
+    @abstractmethod
+    def formato_anotacao_esperado(self) -> BBoxFormat:
+        ...
+
+    @property
+    @abstractmethod
+    def score_range_observado(self) -> tuple:
+        """
+        Faixa de confiança que este framework costuma produzir.
+        O YOLOv8n não passa de 0,907; o Detectron2 chega a 0,995.
+        """
+
+    def preparar_dataset(self, spec: DatasetSpec) -> str:
+        """Converter o dataset para o formato do framework é trabalho futuro."""
+        raise NotImplementedError(
+            "Conversão de formatos na entrada está fora do escopo desta versão")
+
+    @abstractmethod
+    def carregar_modelo(self, caminho: str) -> None:
+        ...
+
+    @abstractmethod
+    def extrair_budget(self, caminho: str) -> TrainingBudget:
+        """Lê os hiperparâmetros do modelo salvo."""
+
+    @abstractmethod
+    def inferir(self, caminho_imagem: str, slicing: Optional[SlicingConfig],
+                score_threshold: float) -> list:
+        """
+        Devolve list[Detection]. Coordenadas em float, sem truncar.
+        Classe sempre int.
+        """
+
+
+@dataclass
+class RunSpec:
+    """Uma execução, com tudo que é preciso para reproduzi-la."""
+    backend: str
+    arquitetura: str
+    dataset: DatasetSpec
+    budget: TrainingBudget
+    slicing: Optional[SlicingConfig]
+    inference_score_threshold: float
+    evaluation_score_threshold: float
+    iou_threshold: float = 0.45
+    score_max_observado: Optional[float] = None
+    device: str = "cuda"
+    data_execucao: Optional[str] = None
+    observacoes: str = ""
+
+
+class ComparisonGuard:
+    """Verifica se dois resultados podem ser comparados."""
+
+    @staticmethod
+    def validar(run_a: RunSpec, run_b: RunSpec) -> dict:
+        """
+        Devolve bloqueios (impedem qualquer comparação) e alertas
+        (permitem comparar o formato, não a qualidade).
+        """
+        bloqueios = run_a.dataset.validar_contra(run_b.dataset)
+        alertas = []
+
+        divergencias = run_a.budget.comparavel_com(run_b.budget)
+        if divergencias:
+            alertas.append(
+                "treino não equalizado: " + "; ".join(divergencias))
+
+        if (run_a.evaluation_score_threshold == run_b.evaluation_score_threshold
+                and run_a.score_max_observado and run_b.score_max_observado):
+            if abs(run_a.score_max_observado - run_b.score_max_observado) > 0.05:
+                alertas.append(
+                    f"mesmo limiar ({run_a.evaluation_score_threshold}) para "
+                    f"faixas de confiança diferentes "
+                    f"({run_a.score_max_observado} vs {run_b.score_max_observado})")
+
+        if run_a.iou_threshold != run_b.iou_threshold:
+            bloqueios.append(
+                f"iou_threshold: {run_a.iou_threshold} vs {run_b.iou_threshold}")
+
+        return {
+            "pode_comparar": len(bloqueios) == 0,
+            "bloqueios": bloqueios,
+            "alertas": alertas,
+        }