# Installation Guide

Setup instructions for all supported platforms.

## Quick Install

| Platform | Command |
|----------|---------|
| Ubuntu/Debian | `./setup/install_ubuntu.sh` |
| Arch Linux | `./setup/install_arch.sh` |
| macOS | `./setup/install_macos.sh` |
| Windows | `.\setup\install_windows.ps1` |

After installation:
```bash
source activate.sh          # Linux/macOS
. .\activate.ps1             # Windows PowerShell

python standalone_simulation.py
```

---

## Platform Compatibility

| Feature | Ubuntu | Arch | macOS | Windows | WSL2 |
|---------|--------|------|-------|---------|------|
| **Standalone Simulation** | ✅ | ✅ | ✅ | ✅ | ✅ |
| **ROS 2** | ✅ | ⚠️ AUR | ❌ | ❌ | ✅ |
| **Gazebo** | ✅ | ⚠️ AUR | ❌ | ❌ | ✅ |
| **Full Mode** | ✅ | ⚠️ | ❌ | ❌ | ✅ |
| **GUI Support** | ✅ | ✅ | ✅ | ✅ | ✅ WSLg |

**Legend:**
- ✅ Fully supported
- ⚠️ Available but requires extra setup
- ❌ Not supported

**Recommendation for Windows users:** Use WSL2 for the full experience (ROS 2 + Gazebo).

---

## Ubuntu / Debian

**Tested on:** Ubuntu 22.04 (Jammy), Ubuntu 24.04 (Noble)

```bash
# Run installer
./setup/install_ubuntu.sh

# Activate environment
source activate.sh

# Run simulation
python standalone_simulation.py
```

**Installs:**
- ROS 2 (Humble or Jazzy based on Ubuntu version)
- Gazebo (ros-gz)
- Python packages: pybullet, numpy, pillow, pyinstaller

---

## Arch Linux

**Tested on:** Arch Linux (rolling release)

```bash
# Run installer
./setup/install_arch.sh

# Activate environment
source activate.sh

# Run simulation
python standalone_simulation.py
```

**Installs:**
- Python packages: pybullet, numpy, pillow, pyinstaller
- yay (AUR helper)

**Optional ROS 2 (from AUR):**
```bash
yay -S ros-humble-desktop
yay -S ros-humble-ros-gz
```

---

## macOS

**Tested on:** macOS 12+ (Monterey, Ventura, Sonoma)

```bash
# Run installer
./setup/install_macos.sh

# Activate environment
source activate.sh

# Run simulation
python standalone_simulation.py
```

**Installs:**
- Homebrew (if not present)
- Python 3.11
- Python packages: pybullet, numpy, pillow, pyinstaller

**Note:** ROS 2 and Gazebo are not supported on macOS. Use standalone mode.

---

## Windows

**Tested on:** Windows 10, Windows 11

```powershell
# Open PowerShell as Administrator
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

# Run installer
.\setup\install_windows.ps1

# Activate environment
. .\activate.ps1

# Run simulation
python standalone_simulation.py
```

**Installs:**
- Chocolatey (package manager)
- Python 3.11
- Python packages: pybullet, numpy, pillow, pyinstaller

**Note:** ROS 2 and Gazebo are not supported natively on Windows. Use standalone mode or WSL2 (below).

---

## Windows with WSL2 (Full Linux Experience)

WSL2 lets you run full Linux on Windows with GUI support. This enables ROS 2 and Gazebo!

**Requirements:** Windows 10 (build 19041+) or Windows 11

### Step 1: Install WSL2

Open PowerShell as Administrator:

```powershell
# Install WSL2 with Ubuntu
wsl --install -d Ubuntu-22.04

# set the user name and password
# Then update the system
sudo apt update
sudo apt upgrade

# Restart computer if prompted
```

### Step 2: Enable GUI Support (WSLg)

Windows 11 and recent Windows 10 updates include WSLg (GUI support) automatically.

Verify by opening Ubuntu and running:
```bash
# Test GUI (should open a window)
sudo apt update
sudo apt install x11-apps -y
xclock
```

If xclock appears, GUI is working!

### Step 3: Install Simulation in WSL

Open Ubuntu from Start menu:

```bash
# Clone or copy your project
cd ~
git clone <your-repo-url> simulation
# OR copy from Windows:
# cp -r /mnt/c/Users/YourName/simulation ~/simulation

cd simulation

# Run Ubuntu installer
./setup/install_ubuntu.sh

# Activate
source activate.sh

# Run with GUI
python standalone_simulation.py
```

### WSL2 Tips

**Access Windows files:**
```bash
# Windows C: drive is at /mnt/c/
cd /mnt/c/Users/YourName/Documents
```

**Run from Windows Terminal:**
```powershell
wsl -d Ubuntu-22.04 -e bash -c "cd ~/simulation && source activate.sh && python standalone_simulation.py"
```

**GPU Acceleration (NVIDIA):**

If you have an NVIDIA GPU:
```bash
# Check if GPU is available
nvidia-smi

# PyBullet will use hardware rendering automatically
```

**Troubleshooting WSL GUI:**

If GUI doesn't work:
```bash
# Update WSL
wsl --update

# Set WSL2 as default
wsl --set-default-version 2

# Reinstall Ubuntu
wsl --unregister Ubuntu-22.04
wsl --install -d Ubuntu-22.04
```

**Using VcXsrv (older Windows 10):**

If WSLg isn't available:
```powershell
# Install VcXsrv
choco install vcxsrv -y
```

Then in WSL:
```bash
# Add to ~/.bashrc
export DISPLAY=$(grep -m 1 nameserver /etc/resolv.conf | awk '{print $2}'):0
export LIBGL_ALWAYS_INDIRECT=1

# Start VcXsrv with "Disable access control" checked
# Then run simulation
python standalone_simulation.py
```

---

## Manual Installation

If the install scripts don't work, install manually:

### 1. Python 3.10+

```bash
# Ubuntu/Debian
sudo apt install python3 python3-pip python3-venv

# Arch
sudo pacman -S python python-pip python-virtualenv

# macOS
brew install python@3.11

# Windows
# Download from https://python.org
```

### 2. Create Virtual Environment

```bash
python3 -m venv venv
source venv/bin/activate  # Linux/macOS
# OR
.\venv\Scripts\Activate.ps1  # Windows
```

### 3. Install Python Packages

```bash
pip install -r requirements.txt
```

Or manually:
```bash
pip install pybullet numpy pillow pyinstaller
```

### 4. Run Simulation

```bash
python standalone_simulation.py
```

---

## Troubleshooting

### PyBullet fails to install

Install build tools:

```bash
# Ubuntu/Debian
sudo apt install build-essential

# Arch
sudo pacman -S base-devel

# macOS
xcode-select --install

# Windows
# Install Visual Studio Build Tools
```

### "Cannot connect to X server"

PyBullet GUI requires a display:

```bash
# Use virtual display
sudo apt install xvfb
xvfb-run python standalone_simulation.py

# OR use X11 forwarding
ssh -X user@host
```

### Pillow fails to install

```bash
# Ubuntu/Debian
sudo apt install libjpeg-dev zlib1g-dev

# Arch
sudo pacman -S libjpeg-turbo zlib

# macOS
brew install libjpeg zlib
```

### Permission denied on Windows

Run PowerShell as Administrator:
```powershell
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
```

---

## Verification

After installation, verify packages:

```bash
python -c "import pybullet; print('PyBullet OK')"
python -c "import numpy; print('NumPy OK')"
python -c "from PIL import Image; print('Pillow OK')"
```

All should print "OK".