UR3-OpenVLA

Adaptação dos modelos OpenVLA e OpenVLA-OFT ao braço robótico Universal Robots UR3, equipado com uma garra OnRobot RG2 e duas câmaras Intel RealSense (D435 na cena, D415 no pulso). O projeto cobre todo o ciclo: recolha de um dataset de demonstrações pick-and-place, pré-processamento para o formato RLDS/OXE, fine-tuning com LoRA, fusão dos adaptadores, avaliação e inferência em tempo real no robot.

Projeto desenvolvido no âmbito da unidade curricular de Projeto da Licenciatura em Engenharia Informática da UBI.

Demonstração em vídeo: https://www.youtube.com/watch?v=lI04P4rUPSA

Estrutura do repositório

Caminho	Descrição
robot_controller/	Aplicação de controlo do robot: captura do dataset, teleoperação e inferência remota (ver abaixo)
preprocess_all.py	Constrói os dois datasets TFDS (base e OFT) a partir dos episódios brutos
merge_oft_adapters.py	Funde em lote os adaptadores LoRA do OpenVLA-OFT no modelo base, produzindo checkpoints implantáveis
apply_adapters.py	Funde um único adaptador LoRA do OpenVLA base
eval_project.py	Avaliação offline: métricas L1/accuracy por dimensão
openvla/	Repositório OpenVLA (código de fine-tuning e deploy do modelo base)
openvla-oft/	Repositório OpenVLA-OFT (código de fine-tuning e deploy da variante OFT)

robot_controller/ — aplicação de controlo

Ponto de entrada: web_app.py — aplicação FastAPI que controla o robot, as câmaras, o orquestrador e os controladores de inferência, e serve a interface web (REST + WebSockets + streams MJPEG).

Módulos principais:

• config.py — configuração central: IP do robot, números de série das câmaras, taxas de captura, mapeamentos do comando, URLs dos servidores de inferência.
• robot_manager_rg2.py — ligação ao UR3 via ur_rtde (servoL/moveL, freedrive) e controlo da garra RG2 por URScript.
• camera.py — captura contínua das RealSense num thread produtor com buffer partilhado.
• capture.py — gravação de episódios a 20 Hz para TFRecord (RLDS), com rate guard e deteção de câmara congelada.
• orchestrator.py — máquina de estados dos episódios pick-and-place e sequência automática (circuito Euleriano sobre os pares de posições).
• gamepad.py — teleoperação com comando.
• inference.py / inference_oft.py — ciclos de inferência contra os servidores deploy.py remotos (OpenVLA e OpenVLA-OFT, respetivamente).
• models.py — persistência das posições e dos metadados de episódios (JSON em state/).

Pipeline completo

1. Recolha do dataset — na interface web, definir as 16 posições da mesa e lançar a sequência automática; cada episódio é gravado como episode.tfrecord + metadata.json.
2. Pré-processamento — construir os dois datasets TFDS (recorte 1080×1080, ação de 7 dimensões com wrap dos deltas de rotação para (−π, π], propriocepção de 7 dimensões no OFT):

   python preprocess_all.py

   Produz ur3_rlds_dataset (OpenVLA base) e ur3_oft_dataset (OpenVLA-OFT), ambos registados no OXE dos respetivos repositórios.
3. Fine-tuning — com os scripts finetune.py dos repositórios openvla/ e openvla-oft/ (LoRA rank 32; no OFT, com FiLM, propriocepção e câmara de pulso).
4. Fusão dos adaptadores — produzir checkpoints autónomos prontos para o deploy.py:

   # OFT (em lote, um por checkpoint da run)
   python merge_oft_adapters.py --base_checkpoint <modelo_base> \
       --runs_root <pasta_das_runs> --output_root <pasta_de_saida>
   
   # OpenVLA base (um adaptador)
   python apply_adapters.py --base-model <dir> --adapter <dir> --stats <dataset_statistics.json>

5. Avaliação offline — métricas L1 e accuracy (tolerância 0,05 no espaço normalizado [−1, 1]), por dimensão e globais, na fração de validação:

   python eval_project.py --model_paths '["<checkpoint_fundido>"]' --ur3_data_root_dir <raiz_dos_datasets>

6. Inferência no robot — arrancar os servidores deploy.py remotos e usar as páginas /inference (base) e /inference_oft da interface web.

Requisitos

• Python 3.10+ (o ambiente de treino dos repositórios OpenVLA usa 3.10)
• Robot: ur_rtde, pygame (teleoperação)
• Câmaras: pyrealsense2, opencv-python
• Dados: tensorflow, tensorflow-datasets, numpy
• Modelos: torch, transformers, peft, draccus
• Interface: fastapi, uvicorn, requests, json_numpy

Resultados

O OpenVLA base afinado falhou em todas as tentativas no robot real, enquanto o OpenVLA-OFT atingiu 88,9 % de taxa de sucesso (40/45) em tarefas pick-and-place. Ver a demonstração em vídeo.