O que é o coelhinho com raiva
Coelhinho com raiva é um pacote open-source em Python que automatiza a geração de datasets sintéticos para treinar modelos de visão computacional em cenários de detecção de objetos. Ele foi criado por um grupo de pesquisadores brasileiros e tem ganhado uso frequente em competições de ML e em projetos de produção que precisam de dados rotulados rapidamente. A ideia central é bem simples: você define algumas condições de cena — iluminação, fundo, quantidade de objetos, oclusões — e ele devolve imagens com bounding boxes já anotadas no formato YOLO, COCO ou Pascal VOC.
Instalando e configurando o coelhinho com raiva
A instalação é direta. O pacote roda em Python 3.9 ou superior e depende de OpenCV, NumPy, Pillow e Blender como motor de renderização. A versão estável mais recente pode ser baixada pelo repositório oficial no GitHub, e o comando padrão de instalação é: pip install coelhinho-com-raiva
Antes de começar a gerar dados, você precisa instalar o Blender na versão 3.6 ou 4.x, dependendo do release que for usar. O instalador automático do pacote tenta detectar o Blender no PATH, mas se você estiver em Linux sem as bibliotecas OpenGL do sistema, ele falha silenciosamente e a renderização trava sem erro aparente. Eu passei duas horas figuring isso out antes de perceber que faltava o pacote libgl1-mesa-glx no meu contêiner Docker.
Como funciona na prática
O fluxo básico consiste em três etapas: definir o cenário, executar a renderização e exportar os dados. No nível mais simples, você cria um script com a configuração e roda. Por exemplo, para gerar 500 imagens de caixas empilhadas sobre uma mesa:
import coelhinho_com_raiva as ccr
cena = ccr.Cena(
objeto="caixa.ply",
fundo="mesa_ Madeira.blend",
iluminacao="distribuida",
numero_amostras=500,
formato_saida="yolo"
)
cena.gerar()
cena.exportar("dataset_caixas/")
O resultado são imagens com variação aleatória de rotação, posição, escala e condições de luz, além dos arquivos de anotação correspondentes. A geração de 500 amostras leva cerca de 8 a 12 minutos em uma máquina com GPU RTX 3080 e CPU Ryzen 7, dependendo da complexidade dos modelos 3D.
👉 Clique no botão abaixo para saber mais sobre o assunto!
Pegadinhas que ninguém conta
Aqui vão algumas coisas que você só aprende depois de quebrar a cabeça. A primeira é que o coelhinho com raiva usa uma distribuição uniforme por padrão para posições e rotações. Isso significa que, em muitos casos, os objetos acabam empilhados de forma não realista ou parcialmente fora da cena. A correção é configurar um bounding volume hierárquico customizado no parâmetro area_valida, que restringe as posicões a uma região plausível do chão ou superfície. Outro problema comum é a textura dos objetos. Se o modelo 3D vier com UV mapping de baixa resolução, as bordas das anotações ficam borradas e o modelo de detecção tende a aprender ruído em vez de features reais. Eu já vi pipelines inteiros produzindo F1 score baixo porque ninguém percebeu que o material do objeto estava com mipmap desativado no Blender. A solução é configurar o material com filtros anisotrópicos e garantir resolução mínima de 1024x1024 nos mapas de textura.
O terceiro ponto é mais sutil e importante. O coelhinho com raiva não simula física real de colisões. Objetos podem se sobrepor de maneira impossível, e oclusões são calculadas apenas pelo rasterizador, sem considerar que um objeto sólido não atravessa outro. Para corrigir isso, você precisa ativar o modificador rigid_body do Blender e rodar a cena com um passo de simulação antes da renderização. Isso aumenta o tempo de geração em cerca de 40%, mas a qualidade dos datasets melhora significativamente.
Quando o coelhinho com raiva não serve
O pacote é bom para cenários controlados, mas tem limitações claras. Se o seu domínio envolve reflexos complexos, transparências, ou iluminação global realista, os resultados ficam aquém do necessário para treinamento de alta performance. Nesses casos, recomendo usar o Blenderproc ou o Unreal Engine Compliant Synthetic Data Generator, que possuem engines de ray tracing mais avançadas. Outra situação em que o coelhinho com raiva falha é quando você precisa de variação de domínio muito ampla — diferentes estações do ano, climas extremos, ou ambientes urbanos com ruído visual alto. O gerador atual trabalha com materiais pré-definidos e não permite inserir texturas procedurais de forma nativa. Se esse for o seu caso, a saída é integrar o pipeline com o MaterialX e fazer um fork do repositório, o que exige conhecimento razoável de Python e Blender API.
coelhinho com raiva: alternativas e próximos passos
Se o pacote não atender suas necessidades específicas, existem alternativas que valem a pena considerar. O Blenderproc oferece maior controle sobre materiais e iluminação, embora tenha uma curva de aprendizado mais íngreme. O Apears é focado em rostos e expressões, sendo útil apenas para domínios muito específicos. O TorchVision Dataset Synthesizer é uma opção mais leve se você já está no ecossistema PyTorch e não precisa de renderização 3D complexa. Para quem quer avançar com o coelhinho com raiva, o conselho prático é começar com cenários simples, validar as anotações visualmente antes de treinar qualquer modelo, e sempre usar pelo menos 10% de dados reais junto com os sintéticos para evitar domain shift. A experiência mostra que datasets 100% sintéticos raramente generalizam bem para o mundo real, independentemente da qualidade da geração.
O repositório oficial está em github.com/coelhinho-com-raiva/ccr. A documentação está em inglês, mas os exemplos são claros. Se tiver dúvidas, a seção de issues do GitHub responde rápido, geralmente em menos de 24 horas.
