mehdibourahla/jewelry-search

Jewelry Search - Visual Similarity Finder

AI-powered search tool to instantly find similar professional jewelry photos using your amateur photos. Upload once, search forever.

Features

• —One-Time Studio Setup: Upload all studio jewelry photos once, index persists forever
• —Instant Search: Upload an amateur photo, get similar studio photos in seconds
• —HEIC/iPhone Support: Works seamlessly with iPhone photos
• —Visual Similarity: Uses YOLO detection + CLIP embeddings for accurate matching
• —Adjustable Results: Choose how many matches to return (1-50)
• —Easy Download: One-click ZIP download of all matched photos
• —Privacy-First: Runs completely offline on your computer

Quick Start

1. Installation

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

2. Launch the Search Tool

./launch_search.sh

The tool will open in your browser at http://localhost:8501

3. Setup Studio Index (One-Time)

Navigate to the "Setup Studio Index" tab:

1. 1.Click "Upload Studio Photos ZIP"
2. 2.Select your ZIP file containing all studio jewelry photos (up to 5GB)
3. 3.Click "🚀 Build Index"
4. 4.Wait for indexing to complete (progress bar shows status)

This only needs to be done once! The index is saved to disk and reused for all future searches.

4. Search for Similar Jewelry

Navigate to the "Search" tab:

1. 1.Drag and drop a single amateur jewelry photo
2. 2.Results appear instantly showing the most similar studio photos
3. 3.Adjust the number of matches using the sidebar slider (1-50)
4. 4.Click "📥 Download All Matches as ZIP" to save the results

5. Repeat Searches

You can upload as many amateur photos as you want - the search is instant!

How It Works

┌─────────────────┐
│ Amateur Photo   │
│ (Your Upload)   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ YOLO Detection  │ ← Detects jewelry in photo
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ CLIP Embedding  │ ← Creates visual fingerprint
└────────┬────────┘
         │
         ▼
┌─────────────────┐      ┌──────────────────┐
│ Vector Search   │◄─────│ Studio Index     │
│ (Qdrant)        │      │ (Pre-built)      │
└────────┬────────┘      └──────────────────┘
         │
         ▼
┌─────────────────┐
│ Top-K Matches   │ → Displayed side-by-side
└─────────────────┘

Index Storage

• —Location: studio_index/ directory
• —Contents: Embeddings, metadata, and original photo paths
• —Size: ~1-2MB per 100 photos
• —Persistence: Reused across sessions until cleared

Supported Formats

• —Photos: JPG, JPEG, PNG, HEIC, HEIF
• —Upload: ZIP files up to 5GB

Tips for Best Results

1. 1.Clear Studio Photos: Better quality studio photos = better matches
2. 2.Good Lighting: Amateur photos should have clear visibility of the jewelry
3. 3.Single Jewelry Piece: YOLO works best when only one jewelry piece is visible
4. 4.Adjust Match Count: Try different values (5, 10, 20) to see more or fewer options

Troubleshooting

"No jewelry detected"

• —Ensure the photo shows jewelry clearly
• —Try a different photo with better lighting
• —Make sure only one jewelry piece is prominently visible

"Index not found"

• —Go to "Setup Studio Index" tab
• —Upload your studio photos ZIP
• —Build the index

Slow indexing

• —Normal for large collections (100+ photos)
• —Indexing only happens once
• —Progress bar shows current status

Project Structure

jewelry-finder/
├── jewelry_search.py          # Main search application
├── launch_search.sh           # Launch script
├── SEARCH_GUIDE.md            # Detailed user guide
├── src/
│   ├── preprocessing.py       # YOLO jewelry detection
│   ├── embedding.py           # CLIP visual embeddings
│   ├── indexing.py            # Qdrant vector search
│   └── config.py              # Configuration
├── studio_index/              # Persisted index (auto-created)
├── test_setup.py              # Installation verification
└── requirements.txt           # Python dependencies

Requirements

• —Python 3.8+
• —4GB+ RAM
• —~500MB disk space for models
• —CUDA GPU (optional, for faster processing)

Technical Stack

• —YOLO: Ultralytics YOLOv8 (jewelry detection)
• —CLIP: OpenAI CLIP via OpenCLIP (ViT-B-32)
• —Vector Search: Qdrant
• —UI: Streamlit
• —Image Processing: Pillow, pillow-heif

License

MIT License - See LICENSE file for details

Support

For issues or questions:

1. 1.Run python test_setup.py to verify installation
2. 2.Check the SEARCH_GUIDE.md for step-by-step instructions
3. 3.Ensure studio index is built before searching

Next Steps

1. 1.Run ./launch_search.sh to start the search tool
2. 2.Build your studio index with all professional photos
3. 3.Upload amateur photos and find matches instantly
4. 4.Download matched photos for your website or catalog