HF_HUB_UPLOAD_GUIDE.md

# Guide: Upload to Hugging Face Hub

This guide explains how to upload the WearIT Garment Mask model to Hugging Face Hub.

## Prerequisites

1. **Hugging Face Account**
   - Create an account at https://huggingface.co/join
   - Generate an access token at https://huggingface.co/settings/tokens
   - Use a "Write" token for uploading

2. **Install Hugging Face CLI**
   ```bash
   pip install huggingface_hub
   ```

3. **Login to Hugging Face**
   ```bash
   huggingface-cli login
   # Enter your access token when prompted
   ```

## Repository Structure for HF Hub

Your repository should have this structure:

```
wearit-garment-mask/
├── README.md                      # Model card (already created)
├── config.json                    # Model configuration (already created)
├── pipeline.py                    # GarmentMaskPipeline class (already created)
├── garment_mask_processor.py      # Core processor
├── resize_image_processor.py      # Image preprocessing
├── mask_utils.py                  # Utility functions
├── mappings.py                    # Body part mappings
├── requirements.txt               # Dependencies (updated)
├── example_usage.py              # Usage examples (already created)
├── .gitignore                     # Git ignore file (already created)
│
├── SCHP/                          # SCHP module
│   ├── __init__.py
│   ├── networks/
│   └── utils/
│
├── DensePose/                     # DensePose wrapper
│   └── __init__.py
│
├── densepose/                     # DensePose from Detectron2
│   └── [densepose files]
│
├── detectron2/                    # Detectron2 framework
│   └── [detectron2 files]
│
└── chkpt/                         # Model checkpoints
    ├── DensePose/
    │   ├── model_final_162be9.pkl
    │   ├── densepose_rcnn_R_50_FPN_s1x.yaml
    │   └── Base-DensePose-RCNN-FPN.yaml
    └── SCHP/
        ├── exp-schp-201908301523-atr.pth
        └── exp-schp-201908261155-lip.pth
```

## Method 1: Using Python API (Recommended)

### Step 1: Prepare the repository

```python
from huggingface_hub import HfApi, create_repo

# Initialize API
api = HfApi()

# Create repository (first time only)
repo_id = "your-username/wearit-garment-mask"
create_repo(repo_id, repo_type="model", exist_ok=True)
```

### Step 2: Upload files

```python
from huggingface_hub import upload_folder

# Upload entire folder
upload_folder(
    folder_path=".",
    repo_id=repo_id,
    repo_type="model",
    ignore_patterns=[
        ".git/*",
        ".gitignore",
        "output/*",
        "*.pyc",
        "__pycache__/*",
        "*.tmp",
        "tmp/*",
        "densepose_/tmp/*"
    ]
)
```

### Step 3: Verify upload

Visit your model page: `https://huggingface.co/your-username/wearit-garment-mask`

## Method 2: Using Git (Alternative)

### Step 1: Clone the repository

```bash
# Install git-lfs for large files
git lfs install

# Clone your HF repository
git clone https://huggingface.co/your-username/wearit-garment-mask
cd wearit-garment-mask
```

### Step 2: Copy files

```bash
# Copy all necessary files
cp -r /path/to/your/project/* .

# Track large files with git-lfs
git lfs track "*.pkl"
git lfs track "*.pth"
git lfs track "*.bin"
```

### Step 3: Commit and push

```bash
git add .
git commit -m "Initial upload of WearIT Garment Mask model"
git push
```

## Handling Large Checkpoint Files

Model checkpoints are large (>100MB). Options:

### Option A: Include in Repository (Simple but large)

```python
# Track with git-lfs
git lfs track "chkpt/**/*.pkl"
git lfs track "chkpt/**/*.pth"

# Or using Python API
upload_folder(
    folder_path=".",
    repo_id=repo_id,
    repo_type="model"
)
```

### Option B: External Storage (Recommended for very large files)

1. Upload checkpoints to a separate storage (Google Drive, S3, etc.)
2. Modify `pipeline.py` to download checkpoints on first use:

```python
from huggingface_hub import hf_hub_download

def download_checkpoint_if_needed(checkpoint_name, cache_dir="./chkpt"):
    local_path = os.path.join(cache_dir, checkpoint_name)
    if not os.path.exists(local_path):
        # Download from HF Hub or external URL
        downloaded = hf_hub_download(
            repo_id="your-username/wearit-garment-mask-checkpoints",
            filename=checkpoint_name,
            cache_dir=cache_dir
        )
        return downloaded
    return local_path
```

### Option C: Host Checkpoints on HF Hub (Best practice)

Create a separate repository for checkpoints:

```bash
# Create checkpoint repository
huggingface-cli repo create wearit-garment-mask-checkpoints

# Upload checkpoints
huggingface-cli upload wearit-garment-mask-checkpoints ./chkpt
```

Then reference in your main model:

```python
from huggingface_hub import snapshot_download

checkpoint_dir = snapshot_download(
    repo_id="your-username/wearit-garment-mask-checkpoints",
    cache_dir="./chkpt"
)
```

## Testing Your Uploaded Model

After uploading, test that it works:

```python
from transformers import pipeline

# Load from HF Hub
pipe = pipeline(
    "image-segmentation",
    model="your-username/wearit-garment-mask",
    trust_remote_code=True
)

# Test
results = pipe("test_image.jpg", garment_types="upper")
print("✓ Model loaded successfully from HF Hub!")
```

## Updating Model Files

### Update specific files

```python
from huggingface_hub import upload_file

upload_file(
    path_or_fileobj="pipeline.py",
    path_in_repo="pipeline.py",
    repo_id=repo_id,
    repo_type="model"
)
```

### Update entire repository

```python
upload_folder(
    folder_path=".",
    repo_id=repo_id,
    repo_type="model"
)
```

## Best Practices

1. **Version Control**
   - Tag releases: `git tag v1.0.0 && git push --tags`
   - Use semantic versioning

2. **Model Card**
   - Keep README.md updated with latest performance metrics
   - Add example images (create `example_images/` folder)

3. **License**
   - Clearly state licenses for all components
   - Apache 2.0 for your code
   - Respect DensePose (Apache 2.0) and SCHP (MIT) licenses

4. **Citations**
   - Credit original model authors
   - Provide BibTeX entries

5. **Testing**
   - Test model download and inference before announcing
   - Create a demo space on HF Spaces (optional)

## Creating a Gradio Demo (Optional)

Create `app.py` for a HF Space:

```python
import gradio as gr
from pipeline import GarmentMaskPipeline

# Initialize pipeline
pipe = GarmentMaskPipeline(device="cpu")

def process_image(image, garment_type):
    results = pipe(image, garment_types=garment_type)
    result = results[0]
    return result["masks"][garment_type]["person_mask"]

demo = gr.Interface(
    fn=process_image,
    inputs=[
        gr.Image(type="pil", label="Input Image"),
        gr.Dropdown(["upper", "lower", "dress"], label="Garment Type")
    ],
    outputs=gr.Image(type="pil", label="Generated Mask"),
    title="WearIT Garment Mask Generator",
    description="Generate garment masks for image inpainting"
)

demo.launch()
```

## Troubleshooting

### Large file errors
```bash
# Increase git buffer
git config http.postBuffer 524288000

# Or use git-lfs
git lfs install
```

### Authentication errors
```bash
# Re-login
huggingface-cli login --token YOUR_TOKEN
```

### Module import errors
- Ensure all dependencies are in `requirements.txt`
- Test in clean environment before uploading

## Resources

- [HF Hub Documentation](https://huggingface.co/docs/hub/index)
- [Model Cards Guide](https://huggingface.co/docs/hub/model-cards)
- [Git LFS Documentation](https://git-lfs.github.com/)

## Summary Checklist

- [ ] README.md with complete model card
- [ ] config.json with model configuration
- [ ] pipeline.py with custom Pipeline class
- [ ] requirements.txt with all dependencies
- [ ] .gitignore for temporary files
- [ ] Model checkpoints (in repo or external)
- [ ] Example usage script
- [ ] License file (LICENSE)
- [ ] Test that model loads from HF Hub
- [ ] (Optional) Create demo on HF Spaces

Good luck with your upload! 🚀