Documentation
Everything you need to know about using CatalogMatch.
Quick Start Guide
Get started with CatalogMatch in just a few minutes.
Step 1: Launch the Application
Double-click the CatalogMatch executable to launch the app. On first launch, the app will create a database in your system's application data folder.
Step 2: Upload Historical Catalog
Click "Upload Historical Catalog" and select a folder containing your historical product images. You can optionally include a CSV file with product metadata.
- Supported formats: JPEG, PNG, WebP
- Maximum file size: 10 MB per image
- Recommended image size: 512x512 to 2048x2048 pixels
Step 3: Upload New Products
Click "Upload New Products" and select a folder containing the products you want to match. Again, you can include a CSV file with metadata.
Step 4: Configure and Match
Set your matching preferences:
- Similarity Threshold: Minimum score (0-100) for matches to appear
- Result Limit: Maximum number of matches per product (1-50)
Click "Start Matching" to begin the process.
Step 5: View Results
Browse your results in the grid view. Click any match to see a detailed side-by-side comparison with score breakdowns.
Uploading Products
CatalogMatch supports two ways to upload products: folder upload and CSV metadata.
Folder Upload
Simply drag and drop a folder containing product images onto the upload area. The app will:
- Scan all images in the folder
- Extract visual features automatically
- Use the filename as the product identifier
With CSV Metadata
Include a CSV file in your folder to provide additional product information. The
CSV file should be named products.csv or metadata.csv.
CSV Format
Your CSV file should include the following columns (all optional except filename):
product1.jpg,placemats,SKU-001,Blue Placemat
product2.jpg,dinnerware,SKU-002,White Plate
product3.jpg,textiles,,Cotton Napkin
Column Descriptions
- filename (required): Name of the image file
- category (optional): Product category for filtering
- sku (optional): Product SKU or identifier
- name (optional): Human-readable product name
Notes:
- The CSV must include a header row
- Empty fields are allowed (leave blank or use empty quotes)
- Values with commas should be quoted:
"Red, Blue Placemat" - If no category is provided, products will match against all categories
Running Matches
The matching process compares new products against your historical catalog using visual similarity analysis.
How Matching Works
- Feature Extraction: The app analyzes each image for color, shape, and texture features
- Category Filtering: Products are only compared within the same category (if specified)
- Similarity Scoring: Each comparison generates a score from 0-100
- Ranking: Matches are sorted by similarity score (highest first)
- Filtering: Only matches above your threshold are shown
Matching Parameters
- Similarity Threshold (0-100): Set higher (e.g., 80) to see only very similar products, or lower (e.g., 50) for more matches
- Result Limit (1-50): Control how many matches to show per product
Performance Tips:
- Matching 100 products against 1,000 historical items takes ~30 seconds
- Use categories to speed up matching (fewer comparisons needed)
- Features are cached - re-matching is faster than initial upload
Understanding Results
Results are displayed in a grid showing each new product with its top matches.
Similarity Scores
Scores are color-coded for easy interpretation:
Score Breakdown
Click any match to see detailed scoring:
- Color Score: How similar the color distributions are (50% weight)
- Shape Score: How similar the shapes and contours are (30% weight)
- Texture Score: How similar the patterns and textures are (20% weight)
Exporting Results
Click "Export to CSV" to save all results. The export includes:
- New product information
- Matched product information
- Overall similarity score
- Individual feature scores (color, shape, texture)
License Activation
The free version allows up to 50 products. Upgrade to Pro for unlimited products.
Activating Pro License
- Purchase a Pro license from the pricing page
- You'll receive a license key via email
- In the app, go to Help → Enter License Key
- Paste your license key and click "Activate"
- The app will unlock all Pro features immediately
License Key Format
License keys look like: XXXX-XXXX-XXXX-XXXX
Multiple Computers
Your Pro license can be used on up to 3 computers. Simply enter the same license key on each machine.
Frequently Asked Questions
What image formats are supported?
JPEG (.jpg, .jpeg), PNG (.png), and WebP (.webp) formats are supported. Maximum file size is 10 MB per image.
How accurate is the matching?
Matching accuracy depends on image quality and product similarity. The system analyzes color, shape, and texture features. Products with similar visual characteristics will score higher. For best results, use clear, well-lit product photos with minimal background.
Can I match products without categories?
Yes! If you don't specify categories, products will be matched against the entire historical catalog. However, using categories improves accuracy and speed by limiting comparisons to relevant products.
Where is my data stored?
All data is stored locally on your computer. Windows: %APPDATA%\ProductMatcher\,
macOS: ~/Library/Application Support/ProductMatcher/.
No data is sent to external servers.
Can I delete products from my catalog?
Currently, the app doesn't have a built-in delete feature. To reset your catalog, close the app and delete the database file from the data folder. A delete feature will be added in a future update.
How do I update the app?
Check the download page for the latest version. Download and run the new version - your existing data will be preserved. Auto-update functionality is coming in a future release.
What's the difference between Free and Pro?
The free version limits you to 50 products total (historical + new). Pro removes this limit, allowing unlimited products. All other features are identical. See the pricing page for details.
What is CLIP and how does it improve matching?
CLIP (Contrastive Language-Image Pre-training) is an AI model that understands images at a deeper level than traditional methods. It provides significantly better accuracy for finding similar products.
CLIP vs Legacy Features: CLIP analyzes images holistically using deep learning (512-dimensional embeddings), while legacy features use basic color histograms, shape descriptors, and texture patterns. CLIP is more accurate but requires more processing power.
Do I need a GPU?
No! The app works perfectly on CPU for small to medium catalogs (under 1,000 products). GPU acceleration is optional but recommended for large catalogs or frequent batch processing.
Performance comparison: CPU processes 5-20 images/sec, while GPUs process 100-300 images/sec. For a 500-product catalog, CPU takes ~30 seconds vs 2-5 seconds on GPU.
Which GPUs are supported?
Fully Supported:
- NVIDIA GeForce/RTX series (best support, any recent GPU)
- Apple Silicon M1/M2/M3/M4/M5 (excellent performance)
Limited Support:
- AMD Radeon RX 6000/7000/9000 series only (requires Python 3.12 + ROCm 6.4)
- Older AMD GPUs (RX 5000 and earlier) are NOT supported
See our GPU Setup Guide for detailed instructions and troubleshooting.
How do I enable GPU acceleration?
GPU acceleration is automatic! The app detects your GPU on first launch and downloads the CLIP model (~350MB). You'll see a GPU status indicator in the app showing whether GPU acceleration is active.
First-time setup: The first launch downloads the CLIP model, which takes 1-2 minutes depending on your internet speed. After that, the model is cached locally and loads instantly.
Troubleshooting
App Won't Launch
Windows: If Windows SmartScreen blocks the app, click "More info" then "Run anyway". The app is safe but not yet code-signed.
macOS: If macOS blocks the app, go to System Preferences → Security & Privacy → click "Open Anyway".
Images Not Processing
- Check that images are in supported formats (JPEG, PNG, WebP)
- Verify images are under 10 MB
- Ensure images aren't corrupted (try opening them in an image viewer)
- Check the app logs for specific error messages
Matching Takes Too Long
- Use categories to reduce the number of comparisons
- Process products in smaller batches
- Ensure your computer meets the minimum system requirements
- Close other resource-intensive applications
No Matches Found
- Lower your similarity threshold (try 50 instead of 80)
- Check that categories match between new and historical products
- Verify that historical products were uploaded successfully
- Ensure images are clear and show the actual products
CSV Not Recognized
- Ensure the CSV file is named
products.csvormetadata.csv - Verify the CSV has a header row with column names
- Check that the
filenamecolumn exists and matches your image files - Save the CSV with UTF-8 encoding
License Key Not Working
- Check for typos - license keys are case-sensitive
- Ensure you're copying the entire key (format: XXXX-XXXX-XXXX-XXXX)
- Verify your internet connection (required for activation)
- Contact support if the key still doesn't work
GPU Not Detected
Check GPU Status: Look for the GPU indicator in the app (usually in the status bar or settings). It should show "GPU: Active (CUDA/ROCm/MPS)" or "CPU Mode".
NVIDIA GPUs:
- Update to latest NVIDIA drivers from nvidia.com
- Restart computer after driver installation
- Check if other GPU-accelerated apps work (e.g., games)
AMD GPUs:
- Verify you have RX 6000/7000/9000 series (older GPUs not supported)
- Ensure Python 3.12 is installed (ROCm requires exactly 3.12)
- Install ROCm HIP SDK 6.4 from AMD's website
- Restart computer after ROCm installation
- Run the GPU setup script:
python gpu/setup_gpu.py
Apple Silicon:
- MPS should work automatically on M1/M2/M3/M4/M5 Macs
- Ensure macOS is up to date (10.15 or later)
- If not working, try reinstalling the app
Still not working? The app will automatically fall back to CPU mode, which works perfectly fine for most use cases. See our GPU Setup Guide for detailed troubleshooting.
CLIP Model Download Fails
- Check your internet connection (model is ~350MB)
- Ensure you have 1GB free disk space
- Try restarting the app to retry the download
- Check if your firewall is blocking the download
- Model is cached in:
~/.cache/torch/sentence_transformers/
Processing is Slow Despite Having GPU
- Check GPU status indicator - ensure it shows GPU is active
- Close other GPU-intensive applications (games, video editing, etc.)
- Check GPU temperature - thermal throttling can slow performance
- For AMD GPUs: ROCm on Windows may be slower than NVIDIA CUDA
- Try processing smaller batches (50-100 products at a time)
Still Having Issues?
If you're still experiencing problems, our support team is here to help.