Update README.md

README.md

@@ -11,70 +11,77 @@ pinned: false
 license: mit
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+<h1 align="center">**VISIONARY: AI-Powered Interior Design Engine** 🏡</h1>
 
+<div align="center">
+  
+**Matan Zigelman**  
+*Reichman University*
 
-# 🏡 VISIONARY: AI-Powered Interior Design Engine
-
-> An advanced, multi-modal recommendation system leveraging Deep Learning (CLIP), Unsupervised Clustering (K-Means), and Generative AI to understand stylistic intent and retrieve context-aware interior design architecture.
+</div>
 
 ---
 
-## 📖 Executive Summary
-Welcome to **Visionary**. Traditional visual search engines rely on basic pixel-matching or color histograms, which often fail to grasp the structural and semantic nuances of interior design. This project solves that by utilizing the `openai/clip-vit-base-patch32` vision-language model to project raw images into a 512-dimensional semantic space. By doing so, the system understands abstract concepts—such as "minimalist," "industrial," or "warm lighting"—and retrieves highly accurate room designs based on user inspiration photos or textual descriptions.
+## 📖 Project Overview
+Traditional visual search engines often rely on basic pixel-matching or color histograms, which struggle to grasp the structural and semantic nuances of architectural spaces. **Visionary** was developed as a comprehensive academic and technical showcase to solve this limitation. 
+
+By utilizing the `openai/clip-vit-base-patch32` vision-language model, this project projects raw images into a 512-dimensional semantic space. As a result, the system autonomously understands abstract concepts—such as "minimalist," "industrial," or "warm lighting"—and retrieves highly accurate room designs based on user inspiration photos or textual descriptions.
+
+**Tech Stack:** `Python` | `PyTorch` | `Hugging Face (Transformers, Datasets)` | `Scikit-Learn (K-Means, t-SNE)` | `Pandas` | `Gradio`
 
 ---
 
 ## 🗄️ 1. Dataset Architecture
 
-For the foundation of this engine, we selected the `my_interior_design_dataset` from Hugging Face. This dataset is exceptionally well-suited for high-level visual recommendation tasks.
+For the foundation of this engine, I selected the `my_interior_design_dataset` from Hugging Face. This dataset is exceptionally well-suited for high-level visual recommendation tasks.
 
-* **Total Volume:** 33,453 images (~33,500 in the training split).
-* **Storage Size:** 535 MB.
-* **Standardization:** All image matrices are perfectly uniform at a `256x256` pixel resolution.
-* **Categorical Richness:** Every sample is enriched with two primary ground-truth labels:
-  * **Style:** 11 distinct design classes (e.g., *Rustic, Bohemian, Transitional, Mid-Century Modern*).
-  * **Room:** 5 functional architectural classes (e.g., *Bedroom, Kitchen, Dining Room, Living Room, Bathroom*).
+| Feature | Details |
+| :--- | :--- |
+| **Total Volume** | 33,453 images (~33,500 in the training split). |
+| **Storage Size** | 535 MB. |
+| **Standardization**| All image matrices are perfectly uniform at a `256x256` pixel resolution. |
+| **Style Labels** | 11 distinct design classes (e.g., *Rustic, Bohemian, Transitional*). |
+| **Room Labels** | 5 functional architectural classes (e.g., *Bedroom, Kitchen, Living Room*). |
 
 ---
 
 ## 📊 2. Exploratory Data Analysis (EDA)
 
-Before feeding data into deep neural networks, we conducted rigorous Exploratory Data Analysis to validate structural integrity and uncover hidden visual biases.
+Before feeding data into deep neural networks, I conducted rigorous Exploratory Data Analysis to validate structural integrity and uncover hidden visual biases.
 
 ### 2.1 Initial Sanity Checks & Data Integrity
-* **Missing Value Verification:** We inspected the metadata arrays and confirmed **zero missing values (NaNs)**. Every visual sample is explicitly paired with valid ground-truth labels.
-* **Dimension Uniformity:** Batch tensor operations require exact spatial dimensions. Our checks passed flawlessly—100% of the tested samples maintain the strict 256x256 boundary, eliminating the need for dynamic resizing during training.
+* **Missing Value Verification:** I inspected the metadata arrays and confirmed **zero missing values (NaNs)**. Every visual sample is explicitly paired with valid ground-truth labels.
+* **Dimension Uniformity:** Batch tensor operations require exact spatial dimensions. The checks passed flawlessly—100% of the tested samples maintain the strict 256x256 boundary, eliminating the need for dynamic resizing during training.
 
 ### 2.2 Class Distribution Analysis
 Understanding the distribution of our labels is critical to identifying potential model biases. 
-* **Room Types:** We observed a moderate class imbalance. *Class 4 (Living Room)* is the dominant category with >10,000 samples, whereas *Class 3* contains ~4,000. 
+* **Room Types:** There is a moderate class imbalance. *Class 4 (Living Room)* is the dominant category with >10,000 samples, whereas *Class 3* contains ~4,000. 
 * **Interior Styles:** The stylistic distribution is more balanced, gently sloping from ~4,000 samples down to ~2,100 in the least frequent class.
 * **Takeaway:** While the model has ample data to generate robust embeddings across all vectors, the recommendation engine might naturally perform with higher confidence on Living Rooms due to broader exposure during the embedding phase.
 
 <div align="center">
-  <img src="REPLACE_THIS_WITH_IMAGE_LINK.png" alt="Class Distribution Bar Charts" width="800"/>
+  <img src="https://huggingface.co/spaces/matanzig/Interior-Design-GenAI/resolve/main/plot.png" alt="Class Distribution Bar Charts" />
   <br>
   <em>Figure 1: Distribution of Room Types and Interior Styles across the dataset.</em>
 </div>
 
 ### 2.3 RGB Channel Distribution
 Unlike tabular data, images are composed of pixel intensities across Red, Green, and Blue channels. 
-* **Insights:** The generated histogram reveals a dataset that is predominantly bright and well-lit. Notably, the **Red channel dominates** the higher intensity ranges. This perfectly aligns with real-world interior photography, which heavily features warm ambient lighting, wooden textures, and earth-toned furniture. Our CLIP model utilizes these specific warm-light biases as strong features for calculating room similarities.
+* **Insights:** The generated histogram reveals a dataset that is predominantly bright and well-lit. Notably, the **Red channel dominates** the higher intensity ranges. This perfectly aligns with real-world interior photography, which heavily features warm ambient lighting, wooden textures, and earth-toned furniture. The CLIP model utilizes these specific warm-light biases as strong features for calculating room similarities.
 
 <div align="center">
-  <img src="REPLACE_THIS_WITH_IMAGE_LINK.png" alt="RGB Histogram" width="600"/>
+  <img src="https://huggingface.co/spaces/matanzig/Interior-Design-GenAI/resolve/main/rgb.png" alt="RGB Histogram" />
   <br>
   <em>Figure 2: RGB Pixel Intensity Distribution highlighting warm-tone dominance.</em>
 </div>
 
 ### 2.4 Spatial Variance & The "Mean Image"
-To identify structural patterns, we computed the mathematical "Mean Image" by averaging pixel arrays within specific classes (e.g., Bedrooms).
+To identify structural patterns, I computed the mathematical "Mean Image" by averaging pixel arrays within specific classes (e.g., Bedrooms).
 * **Insights:** The resulting images were highly amorphous and blurry, lacking distinct structural boundaries like beds or counters. This proves a high degree of spatial variance—rooms are photographed from vastly different angles and depths. 
-* **Conclusion:** This strictly validates our decision to use Deep Learning embeddings over traditional computer vision techniques; we need a model that detects *semantic objects*, regardless of where they are spatially located in the frame.
+* **Conclusion:** This strictly validates the decision to use Deep Learning embeddings over traditional computer vision techniques; the system requires a model that detects *semantic objects*, regardless of where they are spatially located in the frame.
 
 <div align="center">
-  <img src="REPLACE_THIS_WITH_IMAGE_LINK.png" alt="Mean Images by Room Type" width="800"/>
+  <img src="https://huggingface.co/spaces/matanzig/Interior-Design-GenAI/resolve/main/mid.png" alt="Mean Images by Room Type" />
   <br>
   <em>Figure 3: Mean Image representation showing high spatial variance.</em>
 </div>
@@ -83,13 +90,13 @@ To identify structural patterns, we computed the mathematical "Mean Image" by av
 
 ## 🧠 3. Semantic Embeddings & Clustering Pipeline
 
-We extracted a randomized, reproducible subset of 5,000 images (`seed=42`) to optimize computational efficiency while fully capturing the dataset's architectural diversity.
+I extracted a randomized, reproducible subset of 5,000 images (`seed=42`) to optimize computational efficiency while fully capturing the dataset's architectural diversity.
 
 ### 3.1 Feature Extraction (CLIP)
-We deployed Hugging Face's `openai/clip-vit-base-patch32`. Leveraging PyTorch (`torch.no_grad()`) and GPU acceleration, we processed the visual data through the transformer, extracting a highly dense **512-dimensional vector** for each image. These vectors capture complex stylistic signatures.
+I deployed Hugging Face's `openai/clip-vit-base-patch32`. Leveraging PyTorch (`torch.no_grad()`) and GPU acceleration, the visual data was processed through the transformer, extracting a highly dense **512-dimensional vector** for each image. These vectors capture complex stylistic signatures.
 
 ### 3.2 Unsupervised K-Means Clustering
-To test the quality of these embeddings, we applied a K-Means clustering algorithm, explicitly instructing it to find 5 clusters (`n_clusters=5`) to mirror our 5 ground-truth room types. 
+To test the quality of these embeddings, I applied a K-Means clustering algorithm, explicitly instructing it to find 5 clusters (`n_clusters=5`) to mirror the 5 ground-truth room types. 
 
 ### 3.3 Dimensionality Reduction (t-SNE) & Coherence
 Projecting 512 dimensions down to a 2D visual scatter plot via t-SNE yielded outstanding results. Rather than a chaotic cloud, the data formed highly cohesive "islands." 
@@ -101,33 +108,27 @@ By cross-tabulating the generated clusters against actual room labels, distinct
 * **Clusters 2 & 3 (Soft-Furnishings):** A logical blending of Bedrooms and Living Rooms, driven by shared semantic textures (rugs, beds, upholstery).
 
 <div align="center">
-  <img src="REPLACE_THIS_WITH_IMAGE_LINK.png" alt="t-SNE Scatter Plot" width="700"/>
+  <img src="https://huggingface.co/spaces/matanzig/Interior-Design-GenAI/resolve/main/tsne.png" alt="t-SNE Scatter Plot" />
   <br>
   <em>Figure 4: t-SNE 2D Projection showing distinct semantic clustering of 512D embeddings.</em>
 </div>
 
-<div align="center">
-  <img src="REPLACE_THIS_WITH_IMAGE_LINK.png" alt="Cross-Tabulation Matrix" width="600"/>
-  <br>
-  <em>Figure 5: Cross-tabulation proving alignment between unsupervised clusters and ground-truth labels.</em>
-</div>
-
 ---
 
 ## 🚀 4. Recommendation Engine & Final Application
 
-The highly coherent 512D matrix was exported as an optimized `.parquet` file to serve as the brain of our production recommendation engine.
+The highly coherent 512D matrix was exported as an optimized `.parquet` file to serve as the core engine of the production application.
 
 ### System Architecture:
-1. **Input Processing:** When a user interacts with the Gradio UI—either by uploading an inspiration photo or typing a conceptual text prompt—the system passes the input through the CLIP processor, translating it into the exact mathematical vector space as our database.
-2. **Cosine Similarity:** The engine measures the geometric angle between the user's vector and the 5,000 vectors in our catalog.
+1. **Input Processing:** When a user interacts with the Gradio UI—either by uploading an inspiration photo or typing a conceptual text prompt—the system passes the input through the CLIP processor, translating it into the exact mathematical vector space as the database.
+2. **Cosine Similarity:** The engine measures the geometric angle between the user's vector and the 5,000 vectors in the catalog.
 3. **Top-K Retrieval:** The algorithm ranks the closest spatial matches and retrieves the top 3 results alongside their exact confidence scores.
 
 <div align="center">
-  <img src="REPLACE_THIS_WITH_IMAGE_LINK.png" alt="Recommendation Engine Results" width="900"/>
+  <img src="https://huggingface.co/spaces/matanzig/Interior-Design-GenAI/resolve/main/pic.png" alt="Recommendation Engine Results" />
   <br>
-  <em>Figure 6: System successfully matching a textual/visual input to real-world interior designs.</em>
+  <em>Figure 5: System successfully matching a textual/visual input to real-world interior designs.</em>
 </div>
 
-### 🎯 Final Verdict
-Testing the complete pipeline confirmed that the system does not simply match raw colors. It successfully extracts and matches abstract architectural concepts and stylistic intent. The backend logic proved highly reliable and was successfully deployed as a fully interactive Hugging Face Space frontend application.
+### 🎯 Conclusion & Technical Achievements
+Testing the complete pipeline confirmed that the system goes far beyond matching raw colors. It successfully extracts and matches abstract architectural concepts and stylistic intent. The backend logic proved highly reliable and was successfully deployed as a fully interactive Hugging Face Space frontend application, demonstrating a complete end-to-end Machine Learning lifecycle.