Skip to main content

🛠️ Prerequisites

Before installing GBC (Generalized Behavior Cloning Framework), you need to prepare your system environment. GBC has two important dependencies that must be installed separately. Follow the steps below to set up your development environment.

1. 🖥️ Configure Base Environment​

📋 System Requirements​

First, ensure your system meets the minimum requirements:

  • 🐧 Operating System: Ubuntu 20.04 or higher
  • 🚀 CUDA Version: 11.8 or higher
  • 🐍 Python: 3.10 (will be installed via conda)

You can check your system information with:

# Check Ubuntu version
lsb_release -a

# Check CUDA version (if installed)
nvcc --version
# or
nvidia-smi

📦 Install Miniconda3​

If you don't have Miniconda installed, download and install it from the official Miniconda website.

# Download Miniconda3 (Linux x86_64)
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh

# Install Miniconda3
bash Miniconda3-latest-Linux-x86_64.sh

# Follow the installation prompts and restart your terminal

🌍 Create GBC Environment​

Create a dedicated conda environment for GBC:

# Create conda environment with Python 3.10
conda create -n gbc python=3.10

# Activate the environment
conda activate gbc
💡 Pro Tip

Always remember to activate the gbc environment before working with GBC:

conda activate gbc

2. 🤖 Install Isaac Lab (Optional)​

🤔 When do you need Isaac Lab?
  • ✅ Required: If you want to train robots using GBC's reinforcement learning capabilities
  • 🔄 Optional: If you only plan to use GBC's motion retargeting and standardized data generation features, you can skip this section

Isaac Lab is NVIDIA's robot learning framework built on top of Isaac Sim. If you plan to use GBC for training, you must install the complete Isaac Lab environment.

📚 Installation Tutorial Reference​

For detailed installation instructions, please refer to the Isaac Lab Quickstart Guide.

⚠️ Important Installation Note

If you are using Ubuntu 20.04, you must refer to Isaac Lab Installation with Binaries instead of the steps below, otherwise you may encounter compatibility issues.

⚡ Quick Installation (Ubuntu 22.04+)​

For users running Ubuntu 22.04 or higher, you can use the following commands for quick installation:

Step 1: 📈 Upgrade pip​

pip install --upgrade pip

Step 2: 🌟 Install Isaac Sim​

pip install 'isaacsim[all,extscache]==4.5.0' --extra-index-url https://pypi.nvidia.com

Step 3: 📥 Clone Isaac Lab Repository​

git clone git@github.com:isaac-sim/IsaacLab.git

Step 4: ⚙️ Run Installation Script​

Navigate to the Isaac Lab repository and run the installation script:

cd IsaacLab
./isaaclab.sh --install
# or use the short form: ./isaaclab.sh -i

Step 5: 🔙 Return to Parent Directory​

cd ..
⚠️ Important Security Notice

Our subsequent GBC installation will override some files in the original Isaac Lab repository. Please ensure you:

  • ❌ DO NOT run installation scripts with sudo or elevated privileges
  • ❌ DO NOT use high-privilege user accounts during installation
  • ✅ Exception: Docker environments are safe to use

This ensures proper file permissions and prevents potential system conflicts.

3. 🧑‍🦱 Install SMPL Support Libraries​

GBC requires two essential libraries for SMPL/SMPLH support: human_body_prior and body_visualizer. These repositories are somewhat outdated and cannot be installed directly via pip, requiring manual installation and dependency modifications.

📚 Why Manual Installation?

These libraries contain legacy dependencies that conflict with modern package versions. Manual installation allows us to:

  • Remove conflicting dependency specifications
  • Ensure compatibility with current Python packages
  • Maintain stable SMPL/SMPLH functionality

🗂️ Create Working Directory​

First, create a dedicated directory for these installations:

# Create and navigate to working directory
mkdir smpl_libs && cd smpl_libs

📥 Install human_body_prior​

Step 1: Clone and Navigate​

git clone https://github.com/nghorbani/human_body_prior.git && cd human_body_prior

Step 2: Remove Conflicting Dependencies​

Remove the problematic pytorch-lightning and pytorch3d lines from requirements.txt:

# Option 1: Use sed command to remove specific lines
sed -i '/pytorch-lightning/d; /pytorch3d/d' requirements.txt

# Option 2: Manual editing (if sed doesn't work)
# Open requirements.txt and manually delete the lines containing:
# - pytorch-lightning
# - pytorch3d

Step 3: Install in Development Mode​

python setup.py develop

Step 4: Return to Working Directory​

cd ..

🎨 Install body_visualizer​

Step 1: Clone and Navigate​

git clone https://github.com/nghorbani/body_visualizer.git && cd body_visualizer

Step 2: Remove Version Requirements​

Remove version specifications from all libraries in requirements.txt:

# Remove version specifiers (==, >=, etc.) from requirements.txt
sed -i 's/[><=!]*[0-9][0-9.]*[0-9]*//g' requirements.txt

# This will transform:
# trimesh>=3.9.20 -> trimesh
# opencv-python==4.5.3.56 -> opencv-python
# pyrender>=0.1.45 -> pyrender
# pyOpenGL>=3.1.0 -> pyOpenGL
# matplotlib>=3.3.4 -> matplotlib

Step 3: Install in Development Mode​

python setup.py develop

Step 4: Return to Parent Directory​

cd ../..
🚨 Important Warning

DO NOT delete the smpl_libs directory after installation! These repositories must remain in place for GBC to function properly. Removing them will cause import errors and break SMPL/SMPLH functionality.

We recommend keeping this directory in a permanent location such as:

  • ~/libs/smpl_libs/
  • /opt/smpl_libs/ (if you have permissions)
  • Or any other stable directory path

🔍 Verify Installation​

You can verify the installation by testing the imports:

python -c "import human_body_prior; print('human_body_prior: OK')"
python -c "import body_visualizer; print('body_visualizer: OK')"

If both commands execute without errors, the installation was successful! ✅

4. 🖼️ Install System Libraries (Optional)​

GBC uses several system libraries to enhance rendering capabilities and improve training efficiency. While this step is optional, installing these libraries will provide better functionality for visualization and data processing.

🤔 When do you need these libraries?
  • 🎨 imagemagick: For image processing and format conversion
  • 🎬 ffmpeg: For video processing and animation generation
  • 🖥️ tmux: For managing multiple terminal sessions during long training runs

Note: Skipping this step may cause some image rendering functions to fail when saving outputs, but won't affect core GBC functionality.

📦 Installation Commands​

Install the required system libraries using your system package manager:

For Ubuntu/Debian systems:​

sudo apt update
sudo apt install -y imagemagick ffmpeg tmux

For CentOS/RHEL systems:​

# Install EPEL repository first (if not already installed)
sudo yum install -y epel-release

# Install the packages
sudo yum install -y ImageMagick ffmpeg tmux

For Arch Linux:​

sudo pacman -S imagemagick ffmpeg tmux

🔍 Verify Installation​

You can verify the installation by checking the versions:

# Check imagemagick
convert -version

# Check ffmpeg
ffmpeg -version

# Check tmux
tmux -V

📚 What Each Library Does​

  • 🎨 ImageMagick:

    • Converts between image formats
    • Handles image processing operations
    • Required for some visualization outputs

  • 🎬 FFmpeg:

    • Processes video files and animations
    • Converts between video formats
    • Essential for creating training visualizations

  • 🖥️ Tmux:

    • Manages multiple terminal sessions
    • Keeps training processes running in background
    • Useful for long-running experiments
💡 Pro Tip for Training

Using tmux is highly recommended for training sessions:

# Start a new tmux session for training
tmux new-session -s gbc_training

# Detach from session (Ctrl+B, then D)
# Reattach later with:
tmux attach-session -t gbc_training

🎯 Next Steps​

Once you have completed the environment setup:

  1. ✅ Base Environment: Conda environment with Python 3.10
  2. ✅ Isaac Lab (if needed): Complete Isaac Lab installation
  3. ✅ SMPL Support: human_body_prior and body_visualizer libraries
  4. ✅ System Libraries (optional): imagemagick, ffmpeg, and tmux

You're now ready to proceed with installing the GBC framework itself! 🚀 Continue to the next section for GBC installation instructions.