A Python-based photo compositing system for the anti-racism campaign "Beneath the Surface" with the message "Different faces, same foundation".

This tool creates powerful visual statements by combining uploaded photos with skeleton overlays, demonstrating that beneath our different external appearances, we all share the same human foundation.

Campaign Message: "Different faces, same foundation"
Call to Action: "Take Part"
Partner Organization: Stand Up To Racism

• ✅ AI Image Generation: Complete (100% technical success)
• ✅ Photo Compositing: Complete and tested
• ✅ Face Detection: Working with OpenCV
• ✅ Background Removal: Working with rembg AI
• ✅ Command Line Interface: Fully functional
• ✅ Metadata Generation: Complete with campaign info
• ✅ Project Organization: Professional structure implemented
• ✅ Path References: All 83 scripts updated for organized structure
• 🚀 Ready for MVP Development: Web interface next

• Python 3.12+
• macOS/Linux (tested on macOS)
• Virtual environment (recommended)

1. Clone and setup environment:

cd /path/to/FaceCampaign
python3 -m venv environment/photo-compositing-env
source environment/photo-compositing-env/bin/activate

2. Install dependencies:

pip install opencv-python Pillow numpy requests rembg onnxruntime

3. Test the system:

python scripts/test_compositor.py

# Basic usage (run from root directory)
python scripts/simplified-photo-compositor.py assets/faces/input_photo.jpg assets/references/skeleton_overlay.png

# Custom output path
python scripts/simplified-photo-compositor.py assets/faces/photo.jpg assets/references/skeleton.png -o outputs/images/my_campaign_image.png

# Adjust parameters
python scripts/simplified-photo-compositor.py assets/faces/photo.jpg assets/references/skeleton.png --split 0.6 --opacity 0.9

# Debug mode
python scripts/simplified-photo-compositor.py assets/faces/photo.jpg assets/references/skeleton.png --debug

FaceCampaign/
├── README.md                           # Main project overview
├── .gitignore                          # Git ignore rules
├── organization_map.json               # Project organization tracking
├── scripts/                            # All Python processing scripts (83 files)
│   ├── simplified-photo-compositor.py  # Main compositor script
│   ├── test_compositor.py             # System validation tests
│   ├── organize_project.py            # Project organization utility
│   ├── update_path_references.py      # Path reference updater
│   └── [80+ other processing scripts] # AI enhancement and testing scripts
├── assets/                             # Source images and reference materials
│   ├── faces/                         # Source face images
│   └── references/                    # Reference skeleton overlays
├── outputs/                            # All generated campaign content
│   ├── images/                        # Final campaign images (SD3 quality)
│   ├── interactive/                   # HTML sliders and web demos
│   ├── quality_tests/                 # Quality comparison outputs
│   └── archives/                      # Historical experiments
├── docs/                              # Documentation and guides
│   ├── development/                   # Setup guides and development logs
│   ├── instructions/                  # Copilot instructions
│   └── legal/                         # Legal and licensing info
├── environment/                       # Virtual environments
│   └── photo-compositing-env/         # Python virtual environment
└── .github/                           # GitHub configuration
    └── copilot-instructions.md        # AI development guidelines

1. 🔍 Face Detection: Uses OpenCV to detect faces in uploaded photos
2. 💀 Skeleton Loading: Loads and prepares skeleton overlay image
3. 🎨 Half-Split Composite: Creates seamless blend between face and skeleton
4. 📝 Campaign Elements: Adds subtle campaign watermark
5. 💾 Output Generation: Saves high-quality PNG with metadata

• Preserves Original Faces: 100% authentic face preservation (no AI interpretation)
• Professional Blending: Smooth transitions with configurable blend zones
• Metadata Generation: Comprehensive processing information and campaign data
• Flexible Parameters: Adjustable split position, opacity, and blending
• Error Handling: Robust error handling with informative messages

python scripts/simplified-photo-compositor.py [OPTIONS] INPUT_IMAGE SKELETON_OVERLAY

Arguments:
  INPUT_IMAGE      Path to input photo (e.g., assets/faces/photo.jpg)
  SKELETON_OVERLAY Path to skeleton overlay image (e.g., assets/references/skeleton.png)

Options:
  -o, --output     Output path (optional, defaults to outputs/images/)
  --debug          Enable debug output
  --split FLOAT    Split position (0.0-1.0, default: 0.5)
  --blend INT      Blend zone width in pixels (default: 20)
  --opacity FLOAT  Skeleton opacity (0.0-1.0, default: 0.85)
  -h, --help       Show help message

Each processing run generates:

1. Campaign Image: High-quality PNG with half-face, half-skeleton composite
2. Metadata JSON: Complete processing information including:
   • Campaign messaging and organization info
   • Face detection results and coordinates
   • Processing parameters and statistics
   • Timestamp and file information

{
  "campaign": {
    "name": "Beneath the Surface",
    "message": "Different faces, same foundation",
    "call_to_action": "Take Part",
    "organization": "Stand Up To Racism"
  },
  "processing": {
    "face_detected": true,
    "face_region": {"x": 128, "y": 128, "width": 256, "height": 256},
    "parameters": {"split_position": 0.5, "blend_zone": 20}
  }
}

python scripts/test_compositor.py

This validates:

• ✅ Package imports (OpenCV, rembg, NumPy)
• ✅ Face detection functionality
• ✅ Background removal AI model
• ✅ Image processing pipeline
• ✅ Test image generation

# Use your own photo and skeleton overlay
python scripts/simplified-photo-compositor.py assets/faces/my_photo.jpg assets/references/my_skeleton.png

python scripts/simplified-photo-compositor.py assets/faces/portrait.jpg assets/references/skull.png

python scripts/simplified-photo-compositor.py assets/faces/portrait.jpg assets/references/skull.png --split 0.4

python scripts/simplified-photo-compositor.py assets/faces/portrait.jpg assets/references/skull.png --opacity 0.7

python scripts/simplified-photo-compositor.py assets/faces/portrait.jpg assets/references/skull.png --blend 40

This system is designed to integrate with:

• Web Interface: Nuxt.js frontend for photo uploads
• Community Gallery: Rotating display of participant images
• Social Sharing: Generated images optimized for social media
• Partner Organizations: Integration with Stand Up To Racism

• Input Photos: User must own rights or have permission
• Skeleton Overlays: Use Creative Commons or licensed medical illustrations
• Output Images: Licensed for campaign use and social sharing

• Creative Commons medical illustrations (~$195/year)
• Wikimedia Commons anatomical drawings
• Licensed stock photography for professional campaigns

1. Face landmark detection for more precise compositing
2. Animated GIF generation for social media
3. Batch processing for multiple images
4. Custom skeleton overlay generation

Ready for integration with:

• Frontend: Nuxt.js photo upload interface
• Backend: .NET Core 8 API for processing
• Storage: Azure Blob Storage for images
• Gallery: Community participation display

Face not detected:

• Ensure good lighting and clear face visibility
• Try different angles or closer shots
• System will use center region if no face detected

Package installation errors:

• Use virtual environment: python3 -m venv photo-compositing-env
• Install cmake if needed: brew install cmake
• Update pip: pip install --upgrade pip

Memory issues with large images:

• Images are automatically resized for processing
• Use --debug flag to see processing details

python scripts/simplified-photo-compositor.py assets/faces/input.jpg assets/references/skeleton.png --debug

Provides detailed logging of:

• Face detection coordinates
• Image processing steps
• Blend zone calculations
• Error details and stack traces

The system has achieved:

• ✅ 100% Technical Success: All dependencies working
• ✅ Authentic Face Preservation: No AI interpretation artifacts
• ✅ Professional Quality: High-resolution output suitable for campaigns
• ✅ User-Friendly Interface: Simple command-line operation
• ✅ Comprehensive Documentation: Ready for team collaboration

1. Web Interface Development: Create Nuxt.js frontend for easy photo uploads
2. Azure Deployment: Deploy to cloud infrastructure for scalability
3. Community Gallery: Build rotating display of participant images
4. Social Integration: Add direct sharing to social media platforms
5. Partnership Features: Integrate with Stand Up To Racism organization

🎯 Campaign Message: "Different faces, same foundation"
📢 Take Part: Create your own "Beneath the Surface" image today!
🤝 Support: Stand Up To Racism

Ready for MVP web development phase ✨