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)

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

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()

Image catalog + triplets: Darebal/furniture-catalog
Code: github.com/Baredal/thesis_furnitures

Citation

@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 and Sklad Mebliv for non-commercial academic research only.

Downloads last month: 17

Darebal
/

furniture-compatibility-siamese