---
  license: mit
  library_name: pytorch
  tags:
    - image-retrieval
    - metric-learning
    - siamese-network
    - furniture
    - compatibility
    - triplet-loss
  pipeline_tag: image-to-image
---

# Furniture Compatibility Siamese Network

Models and retrieval artifacts from the bachelor's thesis **"Visual Furnishings Compatibility Learning and Retrieval Using Machine Learning"** (Ukrainian Catholic University, 2026).

## Architecture

Siamese ResNet18 · embedding head: Linear(512→256) → BN → ReLU → Linear(256→128) · L2-normalised output · triplet margin loss (margin=1.0) · AdamW + linear warmup + ReduceLROnPlateau · two separate models (bedrooms / living rooms).

## Repo layout

```
bedrooms/
  best_model.pt                 — PyTorch checkpoint (weights + config dict)
  retrieval_embeddings.npz      — 128-d embeddings for all catalog items
  retrieval_index.json          — row → furniture metadata
  retrieval_histograms_bc.npz   — sqrt-encoded RGB histograms (96-d)
living_rooms/
  (same four files)
```

## Quick start (run the app)

```bash
git clone https://github.com/Baredal/thesis_furnitures
cd thesis_furnitures
pip install -r requirements.txt
git lfs install
python download_from_hf.py        # downloads this repo + the image catalog
streamlit run src/app/streamlit_app.py
```

## Load a checkpoint

```python
import torch
from src.ml.model import SiameseResnet18
from huggingface_hub import hf_hub_download

ckpt_path = hf_hub_download("Darebal/furniture-compatibility-siamese",
                             "bedrooms/best_model.pt")
ckpt  = torch.load(ckpt_path, map_location="cpu")
model = SiameseResnet18(embedding_dim=ckpt["config"]["embedding_dim"])
model.load_state_dict(ckpt["model_state_dict"])
model.eval()
```

## Related

- **Image catalog + triplets**: [Darebal/furniture-catalog](https://huggingface.co/datasets/Darebal/furniture-catalog)
- **Code**: [github.com/Baredal/thesis_furnitures](https://github.com/Baredal/thesis_furnitures)

## Citation

```bibtex
@thesis{Strus2026furniture,
  title  = {Visual Furnishings Compatibility Learning and Retrieval Using Machine Learning},
  author = {Yaroslav-Dmytro Strus},
  school = {Ukrainian Catholic University},
  year   = {2026},
  type   = {Bachelor's Thesis}
}
```

## License

Model weights: MIT.  
Training images: not redistributed — sourced from [DeepFurniture](https://huggingface.co/datasets/byliu/DeepFurniture) and [Sklad Mebliv](https://skladmebliv.ua/) for non-commercial academic research only.