# 🔤 CJK Font Support for Hugging Face Spaces

## The Solution: `packages.txt`

Hugging Face Spaces allows you to install system packages (like fonts) using a special file called `packages.txt`. This file works like `requirements.txt` but for system packages installed via `apt-get`.

## Files Created/Updated

### 1. **`packages.txt`** (NEW)
```
fonts-noto-cjk
fonts-noto-cjk-extra
fonts-noto-color-emoji
fonts-liberation
fonts-dejavu-core
```

This tells Hugging Face to run:
```bash
apt-get install fonts-noto-cjk fonts-noto-cjk-extra fonts-noto-color-emoji fonts-liberation fonts-dejavu-core
```

### 2. **Updated `app.py`** and **`app_simple.py`**
- Added proper Linux font paths
- Added font loading verification
- Added fallback handling

## How It Works

1. **During Build**: HF Spaces reads `packages.txt` and installs the listed packages
2. **Font Installation**: The Noto CJK fonts get installed to `/usr/share/fonts/`
3. **App Runtime**: The app searches for fonts in the correct Linux paths
4. **CJK Support**: Japanese, Chinese, and Korean text will display correctly in bounding boxes

## Font Paths on Hugging Face Spaces (Linux)

```python
font_paths = [
    # Primary CJK fonts
    "/usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc",
    "/usr/share/fonts/truetype/noto-cjk/NotoSansCJK-Regular.ttc",
    
    # Fallback fonts
    "/usr/share/fonts/truetype/liberation/LiberationSans-Regular.ttf",
    "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf",
]
```

## To Deploy with Font Support

### Option 1: Update Existing Space
```bash
cd /Users/sangmin/Developer/Qwen2.5-VL/huggingface-space
./update_space.sh
```

### Option 2: Manual Upload
Upload these 4 files to your Space:
1. `packages.txt` - System packages to install
2. `requirements.txt` - Python packages
3. `app.py` - Updated main app
4. `app_simple.py` - Updated simple version

### Option 3: Fresh Deploy
```bash
./deploy.sh YOUR_USERNAME YOUR_SPACE YOUR_TOKEN
```

## Verification

After deployment, check the build logs for:
```
Installing apt packages from packages.txt
Reading package lists...
Setting up fonts-noto-cjk...
```

In the app logs, you should see:
```
✅ Loaded font: /usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc
```

## Result

✅ Japanese text (ひらがな、カタカナ、漢字) will display correctly
✅ Chinese text (简体/繁體) will display correctly  
✅ Korean text (한글) will display correctly
✅ Emoji and symbols will render properly

## Troubleshooting

If fonts still don't work:
1. Check build logs for package installation errors
2. Try different font paths in the app
3. Use `fc-list` command in a debug script to list available fonts

---

**The app now has full CJK font support on Hugging Face Spaces!** 🎌🇨🇳🇰🇷