punimtag/docs/TESTING_GUIDE.md

PunimTag Testing Guide

🧪 Testing with Real Images

Step 1: Prepare Your Test Images

1. Create/Use Photos Directory:

   mkdir -p photos
   

2. Add Test Images:

   • Copy 10-20 photos with faces to the photos/ directory
   • Supported formats: .jpg, .jpeg, .png, .bmp, .tiff, .gif
   • For best results, use photos with clear, front-facing faces
   • Include photos with the same people for face recognition testing

3. Organize by Subdirectories (optional):

   photos/
   ├── events/
   │   ├── wedding_2023/
   │   └── bar_mitzvah/
   ├── family/
   └── synagogue/
   

Step 2: Process Images

# Process all images in photos directory
python punimtag_simple.py

This will:

• Scan all images in photos/ directory (including subdirectories)
• Extract EXIF metadata (GPS, camera info, dates)
• Detect all faces and create encodings
• Store everything in punimtag_simple.db

Step 3: Inspect Results

# Check what was processed
python db_manager.py
# Choose option 1 to inspect database

Step 4: Identify People (Interactive)

# Use the CLI face identifier
python interactive_identifier.py

This will show you unidentified faces and let you name them.

Step 5: Add Tags

# Use the tag manager
python tag_manager.py

Add Jewish organization specific tags like:

• Events: shabbat, wedding, bar_mitzvah, chanukah
• Locations: synagogue, home, israel
• Activities: praying, celebrating, studying

🧹 Database Management

Clean Database (Keep Schema)

python db_manager.py
# Choose option 2

• Removes all data but keeps tables
• Creates automatic backup first

Delete Database Completely

python db_manager.py
# Choose option 3

• Deletes entire database file
• Creates automatic backup first

Inspect Database

python db_manager.py
# Choose option 1

Shows:

• Image/face/people counts
• Top people by frequency
• Most used tags
• Database file size

🔍 Testing Search Functionality

Basic Search Test

from punimtag_simple import SimplePunimTag

tagger = SimplePunimTag()

# Search by person
results = tagger.simple_search(people=["Rabbi Cohen"])
print(f"Found {len(results)} images with Rabbi Cohen")

# Search by tag
results = tagger.simple_search(tags=["wedding"])
print(f"Found {len(results)} wedding images")

# Combined search
results = tagger.simple_search(
    people=["Sarah Goldberg"],
    tags=["shabbat"]
)
print(f"Found {len(results)} images of Sarah at Shabbat")

tagger.close()

📊 Performance Testing

Test with Different Collection Sizes

1. Small Collection (10-50 images):

   • Process time: ~1-5 minutes
   • Good for initial testing

2. Medium Collection (100-500 images):

   • Process time: ~10-30 minutes
   • Test face recognition accuracy

3. Large Collection (1000+ images):

   • Process time: 1+ hours
   • Test batch processing and performance

Monitor Performance

import time
from punimtag_simple import SimplePunimTag

start_time = time.time()
tagger = SimplePunimTag()
processed = tagger.process_directory()
end_time = time.time()

print(f"Processed {processed} images in {end_time - start_time:.2f} seconds")
tagger.close()

🎯 Testing Specific Features

1. Face Recognition Accuracy

1. Process images with same people
2. Identify some faces manually
3. Process new images with same people
4. Check if they're automatically recognized

2. Jewish Organization Tags

from punimtag_simple import SimplePunimTag
from config import get_config

config = get_config()
event_tags = config.get_tag_suggestions('event')
print("Available Jewish event tags:", event_tags[:10])

3. EXIF Metadata Extraction

from punimtag_simple import SimplePunimTag

tagger = SimplePunimTag()
metadata = tagger.extract_metadata("photos/your_image.jpg")
print("Extracted metadata:", metadata)
tagger.close()

4. GPS Location Data

• Use photos taken with smartphones (usually have GPS)
• Check if latitude/longitude are extracted
• Test location-based searches

🐛 Troubleshooting

Common Issues

1. "No faces detected":

   • Check image quality
   • Ensure faces are clearly visible
   • Try different lighting conditions

2. "EXIF data missing":

   • Some images don't have EXIF data
   • System will default to "N/A"
   • This is normal behavior

3. "Face recognition not working":

   • Need multiple photos of same person
   • Faces should be front-facing and clear
   • Check confidence threshold in config

4. "Processing is slow":

   • Normal for large collections
   • Adjust batch size in config
   • Consider using smaller test set first

Debug Mode

# Add debug logging to see what's happening
import logging
logging.basicConfig(level=logging.DEBUG)

from punimtag_simple import SimplePunimTag
tagger = SimplePunimTag()
# ... rest of your code

✅ Validation Checklist

Before moving to GUI development, validate:

• Images are processing without errors
• Faces are being detected correctly
• EXIF metadata is being extracted
• People can be identified and assigned
• Tags can be added and searched
• Database operations work smoothly
• Search functionality returns expected results
• Performance is acceptable for your collection size

🔄 Reset for Fresh Testing

# Clean everything and start fresh
python db_manager.py  # Choose option 2 to clean
rm -f punimtag_config.json  # Reset config
python config.py  # Regenerate default config

📝 Next Steps After Testing

Once testing is successful:

1. GUI Development: Create visual interface
2. Advanced Features: Add clustering, verification tools
3. Performance Optimization: Fine-tune for your specific needs

💡 Testing Tips

1. Start Small: Test with 10-20 images first
2. Use Clear Photos: Better face detection results
3. Same People: Include multiple photos of same people
4. Variety: Test different scenarios (indoor/outdoor, events, etc.)
5. Monitor Progress: Watch console output during processing
6. Backup Often: Use database manager to create backups