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

   pip install huggingface_hub
   

3. Login to Hugging Face

   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

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

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

# 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

# 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

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)

# 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:

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:

# 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:

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:

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

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

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:

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

# Increase git buffer
git config http.postBuffer 524288000

# Or use git-lfs
git lfs install

Authentication errors

# 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
• Model Cards Guide
• Git LFS Documentation

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! 🚀