mjfit

Geometria de colisão convexa exata para MuJoCo: pinos, furos, roscas e engrenagens

Licença

MIT

Visão geral

mjfit é uma biblioteca Python que gera geometria de colisão para tarefas de montagem no MuJoCo: um pino e seu furo a partir de qualquer contorno, um parafuso e sua porca, ou um par de engrenagens que se engrenam, cada um construído com peças convexas cuja união é exatamente a peça. Ela vem do Improbable AI Lab de Pulkit Agrawal no MIT, onde foi escrita para treinar as políticas do artigo Blind Precise Assembly: Proprioceptive Sim-to-Real Peg-in-Hole for Diverse Parts, e é publicada sob a licença MIT no GitHub.

O problema que ela resolve é específico. O MuJoCo só calcula colisões entre formas convexas, e um furo é côncavo. As saídas habituais são a decomposição convexa aproximada, com CoACD ou V-HACD, ou a colisão por campo de distância com sinal (SDF) do MuJoCo sobre uma malha. A decomposição preenche justamente a folga da qual uma tarefa de montagem depende, e a colisão SDF é mais lenta e perde contatos. O mjfit, em vez disso, corta a placa ao redor de um furo em cunhas convexas, faz do pino o furo deslocado para dentro pela folga e varre os dentes de roscas e engrenagens a partir de perfis convexos, de modo que cada aresta do pino fica exatamente a uma folga da aresta do furo e o MuJoCo calcula nativamente a colisão de cada peça. Curvas viram polígonos que as circunscrevem, então um furo redondo nunca é menor do que o desenhado.

Cada gerador retorna uma string MJCF, a partir do Python ou da linha de comando mjfit, e contornos e dimensões são parâmetros, então um único treinamento pode conter milhares de montagens diferentes. A página do projeto executa ao vivo no navegador as políticas do artigo e as comparações do mjfit.

O mjfit tem três geradores. O mjfit.peg recebe o contorno do furo ou do pino, como uma lista de vértices ou uma forma de mjfit.shapes (círculo, retângulo, estádio, trapézio, polígono regular, estrela, qualquer polígono, contornos Bézier com cantos arredondados ou um arquivo CSV), e constrói o outro como seu deslocamento exato pela folga. Opções adicionam material dentro do furo, como uma lingueta USB ou pinos de conector (o pino se torna uma casca oca ao redor deles), uma seção de pega mais larga, uma placa externa convexa com borda mínima, um furo fechado ou uma massa fixa do pino. O mjfit.thread constrói um parafuso e sua porca a partir de perfis de dente métrico ISO, trapezoidal, ACME, quadrado, dente de serra, de arame redondo ou personalizado, de entrada simples ou múltipla e de rosca à esquerda ou à direita. O mjfit.gear constrói uma engrenagem de dentes retos ou um par engrenado com dentes evolventes em dobradiças, com motor opcional; cada dente é um prisma convexo.

As configurações são arquivos YAML com os argumentos de um gerador, e o pacote traz configurações prontas: pinos circular, estrela, USB-A, USB-C, HDMI, RJ45, D-sub (DB9) e XLR3, roscas M10 e M6 e uma perna do FurnitureBench, além de vários pares de engrenagens. Para treinamento, o mjfit.sample_pegs gera montagens aleatórias reproduzíveis a partir de duas famílias (contornos convexos aleatórios com cantos arredondados ou formas primitivas com até três ilhas no furo), e o mjfit.grid distribui muitas montagens em uma única cena com nomes que nunca entram em conflito.

A saída está pronta para uso: cada geom pertence a uma classe padrão com contatos rígidos, os arquivos podem rodar sozinhos ou ser incluídos em uma cena maior, e as malhas podem ser gravadas como arquivos OBJ quando um conversor USD precisar delas. O benchmark do repositório compara o mjfit com CoACD, V-HACD e o SDF de malha do MuJoCo em um pino redondo ou quadrado de 16 mm com folgas de até 20 µm, em CPU e em GPU com o MuJoCo Warp, e traz os comandos que reproduzem cada número.

Por que importa

A montagem rica em contatos é uma das coisas mais difíceis de aprender em simulação, e a parte mais difícil muitas vezes não é o aprendizado, e sim a geometria: se o furo simulado for menor, mais áspero ou mais lento que o real, uma política treinada nele aprende a lição errada. O mjfit coloca pinos, furos, roscas e engrenagens exatos, rápidos e com variação procedural a um pip install de distância para quem usa o MuJoCo, inclusive o MuJoCo Warp para treinar em grande escala numa GPU. O artigo para o qual ele foi criado mostra o que isso permite: políticas de inserção às cegas treinadas inteiramente em simulação que se transferem para um braço real e inserem pinos com formas que nunca viram.

Problema que resolve

O MuJoCo só calcula colisões entre formas convexas, então uma placa com furo precisa ser aproximada. A decomposição convexa fecha a folga da qual depende uma tarefa de inserção, rosqueamento ou engrenamento, e a colisão por campo de distância é lenta e perde contatos. O mjfit constrói cada peça com peças convexas cuja união é exatamente a peça, preservando a folga, e gera milhares de montagens variadas a partir de parâmetros.

Pontos principais

• Constrói pinos e furos, parafusos e porcas e engrenagens que se engrenam para o MuJoCo com peças convexas cuja união é exatamente a peça
• Cada aresta do pino fica exatamente a uma folga da aresta do furo; círculos viram polígonos circunscritos, então os furos nunca são menores que o desenhado
• Em CPU, um pino e seu furo são simulados uma ordem de grandeza mais rápido que o SDF de malha do MuJoCo, com precisão igual ou melhor, segundo o benchmark do repositório
• Configurações incluídas para conectores e fixadores reais: USB-A, USB-C, HDMI, RJ45, D-sub, XLR, roscas M10 e M6, pares de engrenagens
• A amostragem procedural sorteia milhares de montagens reproduzíveis para um único treinamento
• Criado para o artigo do MIT Blind Precise Assembly, cujas políticas de inserção passam da simulação para um braço real

Para quem é

• Pesquisadores que treinam políticas de montagem, inserção, rosqueamento ou engrenamento no MuJoCo ou no MuJoCo Warp
• Equipes de aprendizado robótico que precisam de muitas peças diferentes com folgas apertadas e exatas
• Engenheiros de simulação que chegaram aos limites da decomposição convexa ou da colisão SDF em peças côncavas
• Estudantes de manipulação rica em contatos que querem modelos prontos de conectores e fixadores

Limitações

• Versão inicial: 0.1.0, mantida por um único autor e instalada a partir do GitHub em vez do PyPI
• Só MuJoCo; outros simuladores recebem as malhas como arquivos OBJ, não o modelo de contato
• Gera peças paramétricas (pinos e furos, roscas, engrenagens retas), não modelos CAD arbitrários
• Contatos rígidos exigem um passo de tempo de 1 ms ou menos, e engrenagens em dobradiças exigem o solver PGS do MuJoCo em vez do solver Newton padrão
• As cunhas da rosca perdem um pouco de material na discretização da hélice, então as roscas só são exatas até essa tolerância