Initial commit
This commit is contained in:
Aherobo Ovie Victor
@@ -0,0 +1,286 @@
|
||||
# Viral Velocity - AI-Powered Social Media Image Scorer
|
||||
|
||||
🚀 **Viral Velocity** is an AI-powered mobile application that helps users optimize their social media posts by providing intelligent image scoring and enhancement recommendations.
|
||||
|
||||
## 🎯 What We Built
|
||||
|
||||
We've created a **personalized 4-pillar scoring system** using **OpenAI GPT-4 Vision** that analyzes images for:
|
||||
|
||||
1. **Technical Quality** (25% weight) - Sharpness, resolution, noise, dynamic range, color fidelity
|
||||
2. **Compositional Strength** (25% weight) - Rule of thirds, leading lines, balance, depth, subject isolation
|
||||
3. **Psychological Engagement** (30% weight) - Face detection, emotional resonance, color psychology, storytelling
|
||||
4. **Trend & Zeitgeist** (20% weight) - **Personalized** aesthetic alignment based on user preferences
|
||||
|
||||
### 🌟 **Key Feature: Personalization**
|
||||
The system now supports **user preferences** for personalized scoring:
|
||||
- **Aesthetic:** Y2K, Maximalist, Minimalist, Vintage, etc.
|
||||
- **Niche:** Fashion Influencer, Food Blogger, Business Professional, etc.
|
||||
- **Target Audience:** Gen Z, Millennials, Professionals, etc.
|
||||
- **Content Type:** Instagram Post, LinkedIn Post, TikTok, etc.
|
||||
- **Brand Voice:** Playful, Professional, Casual, etc.
|
||||
|
||||
## 🛠️ Setup Instructions
|
||||
|
||||
### 1. Install Dependencies
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
### 2. Get OpenAI API Key
|
||||
1. Go to [OpenAI Platform](https://platform.openai.com/api-keys)
|
||||
2. Create a new API key
|
||||
3. Copy the key
|
||||
|
||||
### 3. Set Up Environment
|
||||
Create a `.env` file in the project root:
|
||||
```bash
|
||||
OPENAI_API_KEY=your_actual_api_key_here
|
||||
```
|
||||
|
||||
## 🚀 How to Use
|
||||
|
||||
### Option 1: Run the API Server
|
||||
```bash
|
||||
python api.py
|
||||
```
|
||||
The API will be available at `http://localhost:5300`
|
||||
|
||||
**Logs will be saved to:**
|
||||
- `viral_velocity.log` - Main scorer logs
|
||||
|
||||
**Available Endpoints:**
|
||||
- `GET /` - API info
|
||||
- `POST /score-image` - Score an image with base64 data and optional user preferences
|
||||
- `GET /health` - Health check
|
||||
- `GET /scoring-weights` - View current scoring weights
|
||||
- `GET /available-preferences` - Get all available preference options
|
||||
|
||||
### Option 2: Test with Sample Image
|
||||
1. Place a test image named `test_image.jpg` in the project directory
|
||||
2. Run the test script:
|
||||
```bash
|
||||
python test_scorer.py
|
||||
```
|
||||
|
||||
### Option 3: Test Personalized Scoring
|
||||
```bash
|
||||
python test_personalized.py
|
||||
```
|
||||
This will test the system with different user preferences and show how personalization affects scores.
|
||||
|
||||
### Option 4: Use the Web Frontend
|
||||
```bash
|
||||
# Start the API server (serves both API and frontend)
|
||||
python api.py
|
||||
```
|
||||
Then open http://localhost:5300 in your browser for a beautiful web interface!
|
||||
|
||||
### Option 5: View Logs in Real-Time
|
||||
```bash
|
||||
python view_logs.py
|
||||
```
|
||||
This will show you detailed logs of what's happening during the scoring process.
|
||||
|
||||
### Option 6: Use the API
|
||||
```python
|
||||
import requests
|
||||
import base64
|
||||
|
||||
# Encode image to base64
|
||||
with open("image.jpg", "rb") as image_file:
|
||||
encoded_image = base64.b64encode(image_file.read()).decode()
|
||||
|
||||
# Prepare request
|
||||
request_data = {
|
||||
"image": encoded_image,
|
||||
"user_preferences": {
|
||||
"aesthetic": "Y2K",
|
||||
"niche": "Fashion Influencer",
|
||||
"target_audience": "Gen Z",
|
||||
"content_type": "Instagram Post",
|
||||
"brand_voice": "Playful and Trendy"
|
||||
}
|
||||
}
|
||||
|
||||
# Send request
|
||||
response = requests.post("http://localhost:5300/score-image", json=request_data)
|
||||
result = response.json()
|
||||
|
||||
# Get the final score
|
||||
print(f"Viral Score: {result['final_score']}/100")
|
||||
|
||||
# Get detailed breakdown
|
||||
print(f"Technical Quality: {result['technical_quality']['score']}/100")
|
||||
print(f"Compositional Strength: {result['compositional_strength']['score']}/100")
|
||||
print(f"Psychological Engagement: {result['psychological_engagement']['score']}/100")
|
||||
print(f"Trend & Zeitgeist: {result['trend_zeitgeist']['score']}/100")
|
||||
```
|
||||
|
||||
### Option 7: Use in Your Code (Direct)
|
||||
```python
|
||||
from viral_velocity_scorer import ViralVelocityScorer
|
||||
|
||||
# Initialize scorer
|
||||
scorer = ViralVelocityScorer()
|
||||
|
||||
# Analyze an image with personalized preferences
|
||||
user_preferences = {
|
||||
"aesthetic": "Y2K",
|
||||
"niche": "Fashion Influencer",
|
||||
"target_audience": "Gen Z",
|
||||
"content_type": "Instagram Post",
|
||||
"brand_voice": "Playful and Trendy"
|
||||
}
|
||||
|
||||
# Analyze an image
|
||||
result = scorer.analyze_image_efficient("path/to/your/image.jpg", user_preferences)
|
||||
|
||||
# Get the final score
|
||||
print(f"Viral Score: {result['final_score']}/100")
|
||||
|
||||
# Get detailed breakdown
|
||||
print(f"Technical Quality: {result['technical_quality']['score']}/100")
|
||||
print(f"Compositional Strength: {result['compositional_strength']['score']}/100")
|
||||
print(f"Psychological Engagement: {result['psychological_engagement']['score']}/100")
|
||||
print(f"Trend & Zeitgeist: {result['trend_zeitgeist']['score']}/100")
|
||||
|
||||
# Check if preferences were used
|
||||
print(f"Preferences used: {result['user_preferences_used']}")
|
||||
```
|
||||
|
||||
## 📊 Sample Output
|
||||
|
||||
### Generic Scoring (No Preferences)
|
||||
```json
|
||||
{
|
||||
"final_score": 78.5,
|
||||
"technical_quality": {
|
||||
"score": 85,
|
||||
"weight": 0.25,
|
||||
"details": "Image shows good sharpness and color balance..."
|
||||
},
|
||||
"compositional_strength": {
|
||||
"score": 72,
|
||||
"weight": 0.25,
|
||||
"details": "Subject is well-positioned but could benefit from..."
|
||||
},
|
||||
"psychological_engagement": {
|
||||
"score": 82,
|
||||
"weight": 0.30,
|
||||
"details": "Strong emotional appeal with engaging facial expressions..."
|
||||
},
|
||||
"trend_zeitgeist": {
|
||||
"score": 75,
|
||||
"weight": 0.20,
|
||||
"details": "Aligns well with current minimalist aesthetic trends..."
|
||||
},
|
||||
"recommendations": [
|
||||
"Try adjusting the composition to follow the rule of thirds more closely",
|
||||
"Consider enhancing the lighting to create more dramatic shadows",
|
||||
"The color palette could be more vibrant to increase engagement"
|
||||
],
|
||||
"user_preferences_used": null
|
||||
}
|
||||
```
|
||||
|
||||
### Personalized Scoring (Y2K Fashion Influencer)
|
||||
```json
|
||||
{
|
||||
"final_score": 85.2,
|
||||
"technical_quality": {
|
||||
"score": 85,
|
||||
"weight": 0.25,
|
||||
"details": "Image shows good sharpness and color balance..."
|
||||
},
|
||||
"compositional_strength": {
|
||||
"score": 72,
|
||||
"weight": 0.25,
|
||||
"details": "Subject is well-positioned but could benefit from..."
|
||||
},
|
||||
"psychological_engagement": {
|
||||
"score": 82,
|
||||
"weight": 0.30,
|
||||
"details": "Strong emotional appeal with engaging facial expressions..."
|
||||
},
|
||||
"trend_zeitgeist": {
|
||||
"score": 95,
|
||||
"weight": 0.20,
|
||||
"details": "Perfectly aligns with Y2K aesthetic for fashion content targeting Gen Z..."
|
||||
},
|
||||
"recommendations": [
|
||||
"The Y2K aesthetic is spot-on for your target audience",
|
||||
"Consider adding more vibrant, retro color filters to enhance the Y2K vibe",
|
||||
"The fashion elements align perfectly with Gen Z preferences"
|
||||
],
|
||||
"user_preferences_used": {
|
||||
"aesthetic": "Y2K",
|
||||
"niche": "Fashion Influencer",
|
||||
"target_audience": "Gen Z",
|
||||
"content_type": "Instagram Post",
|
||||
"brand_voice": "Playful and Trendy"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 🎨 How the Scoring Works
|
||||
|
||||
### Technical Quality Score (25%)
|
||||
- **Sharpness & Focus** (0-25 points): Image clarity and focus quality
|
||||
- **Resolution & Clarity** (0-25 points): Image resolution and overall clarity
|
||||
- **Image Noise** (0-20 points): Presence of noise and artifacts
|
||||
- **Dynamic Range** (0-15 points): Balance of highlights and shadows
|
||||
- **Color Fidelity** (0-15 points): Natural and well-balanced colors
|
||||
|
||||
### Compositional Strength Score (25%)
|
||||
- **Rule of Thirds** (0-25 points): Subject positioning according to compositional rules
|
||||
- **Leading Lines** (0-20 points): Lines that guide the eye toward the subject
|
||||
- **Balance & Symmetry** (0-20 points): Visual balance and symmetry
|
||||
- **Depth & Framing** (0-20 points): Layering and framing effectiveness
|
||||
- **Subject Isolation** (0-15 points): How well the subject stands out
|
||||
|
||||
### Psychological Engagement Score (30%)
|
||||
- **Presence of Faces** (0-30 points): Face detection and engagement
|
||||
- **Emotional Resonance** (0-25 points): Emotional impact and appeal
|
||||
- **Color Psychology** (0-25 points): Psychological impact of colors
|
||||
- **Storytelling** (0-20 points): Narrative elements and story potential
|
||||
|
||||
### Trend & Zeitgeist Score (20%)
|
||||
- **Aesthetic Alignment** (0-60 points): Alignment with current visual trends
|
||||
- **Authenticity Index** (0-40 points): Genuine and authentic feel
|
||||
|
||||
## 🔧 Customization
|
||||
|
||||
You can modify the scoring weights in `viral_velocity_scorer.py`:
|
||||
|
||||
```python
|
||||
self.weights = {
|
||||
'technical_quality': 0.25, # Change these values
|
||||
'compositional_strength': 0.25, # to adjust scoring
|
||||
'psychological_engagement': 0.30, # priorities
|
||||
'trend_zeitgeist': 0.20
|
||||
}
|
||||
```
|
||||
|
||||
## 📱 Next Steps for Mobile Integration
|
||||
|
||||
1. **API Integration**: The mobile app can call the `/score-image` endpoint
|
||||
2. **Image Enhancement**: Add Gemini's image generation capabilities
|
||||
3. **User Management**: Add user authentication and usage tracking
|
||||
4. **Analytics**: Track scoring patterns and user engagement
|
||||
|
||||
## 🚨 Important Notes
|
||||
|
||||
- **Privacy**: Images are processed temporarily and not stored
|
||||
- **API Limits**: Be mindful of OpenAI API usage limits and costs
|
||||
- **Accuracy**: Scores are AI-generated and should be used as guidance, not absolute truth
|
||||
- **Mobile Optimization**: Consider image compression for faster mobile processing
|
||||
- **Performance**: Uses efficient analysis (3 API calls instead of 8) to reduce costs
|
||||
- **JSON Parsing**: Automatically handles OpenAI's markdown-formatted JSON responses
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
This is a data science-focused implementation. The scoring algorithms and AI integration are the core components. Frontend/backend development for the mobile app will be handled separately.
|
||||
|
||||
---
|
||||
|
||||
**Built with ❤️ using OpenAI GPT-4 Vision for intelligent social media optimization**
|
||||
Reference in New Issue
Block a user