| --- |
| 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. |
|
|
