# robocasa/robocasa-gr1-tabletop-tasks architecture

> Architecture diagram of the GitHub repository robocasa/robocasa-gr1-tabletop-tasks, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/robocasa/robocasa-gr1-tabletop-tasks
- Repository: https://github.com/robocasa/robocasa-gr1-tabletop-tasks

## Overview

##### Project type and purpose
- This is a Python-based simulation framework extension (“robocasa-gr1-tabletop-tasks”) built on top of the RoboCasa core and Robosuite.
- It provides modular definitions of 24 tabletop manipulation tasks for the NVIDIA GR-1 humanoid, plus tooling to download assets, demo tasks, playback demonstration trajectories, and connect to an Isaac-GR00T inference server for closed-loop evaluation.

##### File structure
Top-level components:
- setup.py, requirements.txt – packaging and dependencies
- README.md, LICENSE – documentation and licensing
- images/ – static assets for README
- robocasa/ – the Python package under development
Inside robocasa/:
- environments/ – task/environment definitions (tabletop subpackage)
- models/
– assets/ – static XML/YAML 3D model and scene descriptions
– fixtures/, objects/, robots/, scenes/ – code that constructs scene elements, registers them, and builds gym environments
- macros.py – common constants and macro definitions
- scripts/ – CLI entrypoints:
– download_*.py – fetch and unpack 3D assets into models/assets
– demo_task.py – spin up a Gym environment with random actions for visualization
– playback_dataset.py – replay HDF5 demonstration trajectories in simulation
– gr00t_finetune.py – script to fine-tune GR00T
- utils/ – shared utilities: camera, configuration, sampling, Gym wrappers, texture swapping
Auxiliary folders: gym_utils for Gymnasium support

##### README for additional insights
- Describes integration with Isaac-GR00T: run an inference server (RPC), then run a simulation client that streams observations to the model and receives actions.
- Outlines directories to be populated by download scripts (models/assets).
- Shows sequence of steps for environment creation, model inference, and evaluation.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Scripts
    subgraph "CLI Scripts" 
        direction TB
        DL_Tabletop["download_tabletop_assets.py"]:::scripts
        DL_Kitchen["download_kitchen_assets.py"]:::scripts
        DL_Groot["download_groot_assets.py"]:::scripts
        Demo_Task["demo_task.py"]:::scripts
        Playback["playback_dataset.py"]:::scripts
    end

    %% Python SDK Package
    subgraph "Python SDK (robocasa)" 
        direction TB
        subgraph "Environments Module" 
            direction TB
            Env_Tabletop["tabletop/"]:::package
        end
        subgraph "Scene Builder & Registry"
            direction TB
            Scene_Builder["scene_builder.py"]:::package
            Scene_Registry["scene_registry.py"]:::package
            Scene_Utils["scene_utils.py"]:::package
        end
        subgraph "Fixture Definitions & Registry"
            direction TB
            Fixtures["fixtures/"]:::package
        end
        subgraph "Object Definitions & Utilities"
            direction TB
            Objects["objects/"]:::package
        end
        Robot_Model["gr1_robot.py"]:::package
        Macros["macros.py"]:::package
        subgraph "Utilities"
            direction TB
            Utils["utils/"]:::package
        end
        subgraph "Gymnasium Wrappers"
            direction TB
            Gym_Utils["gym_utils/"]:::package
        end
    end

    %% Asset Store
    Asset_Store["models/assets/"]:::assets

    %% Demo Dataset
    Demo_Dataset["HDF5 Demonstrations"]:::dataset

    %% Simulation Engine
    Simulation["Simulation Engine\n(MuJoCo/Gym)"]:::engine

    %% External Services
    IsaacGroot["Isaac-GR00T RPC Server"]:::external

    %% Output Artifacts
    Outputs["Videos, Metrics, Logs"]:::artifact

    %% Connections
    DL_Tabletop -->|writes assets to| Asset_Store
    DL_Kitchen -->|writes assets to| Asset_Store
    DL_Groot -->|writes assets to| Asset_Store

    Demo_Task -->|uses| Env_Tabletop
    Playback -->|reads| Demo_Dataset
    Playback -->|uses| Env_Tabletop

    Env_Tabletop -->|builds scenes via| Scene_Builder
    Scene_Builder --> Scene_Registry
    Scene_Registry --> Scene_Utils

    Scene_Registry -->|loads| Asset_Store
    Fixtures -->|registered in| Scene_Registry
    Objects -->|registered in| Scene_Registry
    Robot_Model -->|registered in| Scene_Registry

    Env_Tabletop -->|calls| Utils
    Env_Tabletop -->|wraps env with| Gym_Utils

    Env_Tabletop -->|runs on| Simulation
    Simulation -->|renders| Outputs
    Simulation -->|streams obs/actions| IsaacGroot
    IsaacGroot -->|returns actions| Simulation

    gr00t_finetune["gr00t_finetune.py"]:::scripts
    gr00t_finetune -->|reads| Demo_Dataset
    gr00t_finetune -->|writes| Outputs

    %% Click Events
    click DL_Tabletop "https://github.com/robocasa/robocasa-gr1-tabletop-tasks/blob/main/robocasa/scripts/download_tabletop_assets.py"
    click DL_Kitchen "https://github.com/robocasa/robocasa-gr1-tabletop-tasks/blob/main/robocasa/scripts/download_kitchen_assets.py"
    click DL_Groot "https://github.com/robocasa/robocasa-gr1-tabletop-tasks/blob/main/robocasa/scripts/download_groot_assets.py"
    click Demo_Task "https://github.com/robocasa/robocasa-gr1-tabletop-tasks/blob/main/robocasa/scripts/demo_task.py"
    click Playback "https://github.com/robocasa/robocasa-gr1-tabletop-tasks/blob/main/robocasa/scripts/playback_dataset.py"
    click Env_Tabletop "https://github.com/robocasa/robocasa-gr1-tabletop-tasks/tree/main/robocasa/environments/tabletop/"
    click Scene_Builder "https://github.com/robocasa/robocasa-gr1-tabletop-tasks/blob/main/robocasa/models/scenes/scene_builder.py"
    click Scene_Registry "https://github.com/robocasa/robocasa-gr1-tabletop-tasks/blob/main/robocasa/models/scenes/scene_registry.py"
    click Scene_Utils "https://github.com/robocasa/robocasa-gr1-tabletop-tasks/blob/main/robocasa/models/scenes/scene_utils.py"
    click Fixtures "https://github.com/robocasa/robocasa-gr1-tabletop-tasks/tree/main/robocasa/models/fixtures/"
    click Objects "https://github.com/robocasa/robocasa-gr1-tabletop-tasks/tree/main/robocasa/models/objects/"
    click Robot_Model "https://github.com/robocasa/robocasa-gr1-tabletop-tasks/blob/main/robocasa/models/robots/manipulators/gr1_robot.py"
    click Macros "https://github.com/robocasa/robocasa-gr1-tabletop-tasks/blob/main/robocasa/macros.py"
    click Utils "https://github.com/robocasa/robocasa-gr1-tabletop-tasks/tree/main/robocasa/utils/"
    click Gym_Utils "https://github.com/robocasa/robocasa-gr1-tabletop-tasks/blob/main/robocasa/utils/gym_utils/gymnasium_basic.py"
    click Asset_Store "https://github.com/robocasa/robocasa-gr1-tabletop-tasks/tree/main/robocasa/models/assets/"

    %% Styles
    classDef scripts fill:#D8BFD8,stroke:#9370DB,stroke-width:1px
    classDef package fill:#ADD8E6,stroke:#4682B4,stroke-width:1px
    classDef assets fill:#98FB98,stroke:#228B22,stroke-width:1px
    classDef external fill:#FFA500,stroke:#FF8C00,stroke-width:1px
    classDef dataset fill:#D3D3D3,stroke:#A9A9A9,stroke-width:1px
    classDef engine fill:#FFE4B5,stroke:#DAA520,stroke-width:1px
    classDef artifact fill:#F0E68C,stroke:#BDB76B,stroke-width:1px
```
