README.md

---
license: mit
tags:
- outfit-compatibility-modeling
- fashion-recommendation
- multimodal
- pytorch
- graph-neural-networks
---

<a id="top"></a>
<div align="center">
  <h1>👗 OCMCF: Complementary Factorization towards Outfit Compatibility Modeling</h1>

  <p>
    <b>Tianyu Su</b>&nbsp;
    <b>Xuemeng Song</b>&nbsp;
    <b>Na Zheng</b>&nbsp;
    <b>Weili Guan</b>&nbsp;
    <b>Yan Li</b>&nbsp;
    <b>Liqiang Nie</b>
  </p>
</div>

These are the official pre-trained model weights for **OCMCF** (Complementary Factorization towards Outfit Compatibility Modeling), a novel approach designed for outfit compatibility modeling using complementary factorization with graph neural networks.

🔗 **Paper:** [ACM MM 2021](https://dl.acm.org/doi/10.1145/3474085.3475537)
🔗 **GitHub Repository:** [iLearn-Lab/MM21-OCMCF](https://github.com/iLearn-Lab/MM21-OCMCF)
🔗 **Video Introduction:** [Demo](https://files.atypon.com/acm/6091e3d23a3433ff198ae9d4119200ea)

---

## 📌 Model Information

### 1. Model Name
**OCMCF** (Complementary Factorization towards Outfit Compatibility Modeling) Checkpoints.

### 2. Task Type & Applicable Tasks
- **Task Type:** Outfit Compatibility Modeling / Fashion Recommendation / Multimodal Learning
- **Applicable Tasks:** Predicting compatibility scores between fashion items, outfit recommendation, and fill-in-the-blank fashion tasks on the Polyvore dataset.

### 3. Project Introduction
Outfit compatibility modeling is a crucial task in fashion recommendation systems. **OCMCF** introduces a complementary factorization approach that effectively captures compatibility relationships between clothing items through graph neural networks and transformer architectures. The method decomposes outfit compatibility into complementary factors to better model item relationships.

### 4. Training Data Source
The model was trained and evaluated on:
- **Polyvore Outfits** (Full dataset)
- **Polyvore Outfits-D** (Disjoint split for more challenging evaluation)

---

## 🚀 Usage & Basic Inference

These weights are designed to be used directly with the official OCMCF GitHub repository.

### Step 1: Prepare the Environment
Clone the GitHub repository and install dependencies:
```bash
git clone https://github.com/iLearn-Lab/MM21-OCMCF.git
cd MM21-OCMCF/codes
conda create -n ocm-cf python=3.8
conda activate ocm-cf

# Install PyTorch
conda install pytorch==1.6.0 torchvision==0.7.0 cudatoolkit=10.1 -c pytorch

# Install PyTorch Geometric
CUDA=cu101
TORCH=1.6.0
pip install torch-scatter -f https://pytorch-geometric.com/whl/torch-${TORCH}+${CUDA}.html
pip install torch-sparse -f https://pytorch-geometric.com/whl/torch-${TORCH}+${CUDA}.html
pip install torch-geometric

# Install other dependencies
conda install scikit-learn tensorboard
```

### Step 2: Download Model Weights & Data
Download the checkpoint files from this Hugging Face repository and place them in your local `checkpoints/` directory:

```text
checkpoints/
├── disjoint_best.pt
└── nondisjoint_best.pt
```

Ensure you also download and structure the Polyvore dataset as specified in the GitHub repository's Data Preparation section.

### Step 3: Run Inference
To run inference with the downloaded checkpoints:
```bash
cd inference
bash inference_all_tasks.sh ${gpu_id}
```

To train the model from scratch:
```bash
# For Polyvore Outfits dataset
python main.py --polyvore-split nondisjoint

# For Polyvore Outfits-D dataset
python main.py --polyvore-split disjoint
```

---

## 📊 Model Checkpoints

This repository contains the following pre-trained checkpoints:

| Checkpoint | Description | Dataset |
|------------|-------------|---------|
| `disjoint_best.pt` | Best model for disjoint split | Polyvore Outfits-D |
| `nondisjoint_best.pt` | Best model for non-disjoint split | Polyvore Outfits |

---

## ⚠️ Limitations & Notes

**Disclaimer:** This framework and its pre-trained weights are intended for **academic research purposes only**.
- The model requires access to the original Polyvore dataset for full evaluation.
- Performance may vary depending on the dataset split and evaluation metrics used.

---

## 📝⭐️ Citation

If you find our work or these model weights useful in your research, please consider leaving a **Star** ⭐️ on our GitHub repo and citing our paper:

```bibtex
@inproceedings{743aced44b004a3dac16da3feb57edbd,
title = "Complementary Factorization towards Outfit Compatibility Modeling",
author = "Tianyu Su and Xuemeng Song and Na Zheng and Weili Guan and Yan Li and Liqiang Nie",
note = "Publisher Copyright: {\textcopyright} 2021 ACM.; 29th ACM International Conference on Multimedia, MM 2021 ; Conference date: 20-10-2021 Through 24-10-2021",
year = "2021",
doi = "10.1145/3474085.3475537",
series = "MM 2021 - Proceedings of the 29th ACM International Conference on Multimedia",
publisher = "Association for Computing Machinery, Inc",
pages = "4073--4081",
booktitle = "MM 2021 - Proceedings of the 29th ACM International Conference on Multimedia",
}
```

---

## 📄 License

This project is released under the MIT License.