scripts/media/README.md

Media Generation Scripts

Scripts for generating images, banners, and visual assets for topics, causes, and content.

📸 generate_topic_images.py

Generate professional banner images (1200x600) and square thumbnails (400x400) for trending topics and causes using Google Gemini AI.

Features

• AI-Powered Color Schemes: Uses Gemini to suggest professional, thematic color palettes
• Banner Images: 1200x600px hero images for featured stories
• Square Thumbnails: 400x400px images for topic tiles and cards
• Gradient Backgrounds: Professional gradient effects
• Smart Text Wrapping: Automatically wraps long topic names
• Batch Processing: Generate images for multiple topics at once

Setup

1. Get a Gemini API Key:

   • Visit: https://makersuite.google.com/app/apikey
   • Create a new API key

2. Add to .env file:

   GEMINI_API_KEY=your_api_key_here
   

3. Install dependencies (automatic):

   # The script will auto-install if needed:
   # - google-generativeai
   # - pillow
   # - requests
   

Usage

Generate for a single topic:

python scripts/media/generate_topic_images.py --topic "World Press Freedom Day"

Generate for multiple topics from a file:

# Create topics.txt with one topic per line
echo "Artificial Intelligence" > topics.txt
echo "Health & Medicine" >> topics.txt
echo "Climate Action" >> topics.txt

python scripts/media/generate_topic_images.py --topics-file topics.txt

Generate default trending topics:

# No arguments = generates default set of 10 trending topics
python scripts/media/generate_topic_images.py

Custom output directory:

python scripts/media/generate_topic_images.py \
  --topic "Education Reform" \
  --output-dir frontend/public/images/topics

Output

For each topic, generates:

1. Banner: {topic_slug}_banner.png (1200x600)

   • Hero image for featured stories
   • Professional gradient background
   • Large centered text with shadow

2. Square: {topic_slug}_square.png (400x400)

   • Thumbnail for topic cards
   • Circular gradient effect
   • Wrapped text for long names

3. Metadata: metadata.json

   • Color schemes used
   • File paths
   • Topic information

Example Output

data/media/topics/
├── world_press_freedom_day_banner.png
├── world_press_freedom_day_square.png
├── artificial_intelligence_banner.png
├── artificial_intelligence_square.png
├── health_and_medicine_banner.png
├── health_and_medicine_square.png
└── metadata.json

Default Topics

The script generates images for these topics by default:

• World Press Freedom Day
• Business & Markets
• Artificial Intelligence
• Health & Medicine
• Social Media
• Civic Engagement
• Climate Action
• Education Reform
• Housing Policy
• Transportation

Color Scheme Examples

Gemini generates contextual color schemes:

• Politics: Professional blues and reds
• Health: Calming greens and blues
• Technology: Modern purples and blues
• Sports: Energetic oranges and reds
• Environment: Earth tones and greens

Integration with Homepage

The generated images can be used in the homepage:

// Update TOP_STORIES in Home.tsx
const TOP_STORIES = [
  {
    title: 'AI Policy Tracking',
    topic: 'Artificial Intelligence',
    image: '/images/topics/artificial_intelligence_square.png', // Use generated image
    link: '/search?q=artificial+intelligence'
  },
  // ...
]

Troubleshooting

"GEMINI_API_KEY not found"

• Add your API key to .env file
• Or pass with --api-key flag

Font errors

• Script will fallback to default fonts
• On Linux: sudo apt-get install fonts-dejavu

Low quality images

• Images are saved at 95% quality
• For higher quality, edit the quality parameter in the script

Future Enhancements

• Support for Imagen 2 (when available in Gemini API)
• Custom icon/emoji overlays
• Animation support (GIF/WebP)
• Social media sized variants (Twitter, Facebook, etc.)
• Watermark support
• Bulk export to CDN

🎨 Color Scheme Philosophy

The generator uses AI to create professional, accessible color schemes:

1. High Contrast: Ensures text readability (WCAG AA compliant)
2. Thematic Relevance: Colors match topic context
3. Brand Consistency: Works with Open Navigator's primary colors
4. Professional Look: News/media-appropriate palettes

📝 Notes

• Images are generated programmatically (no API image generation yet)
• Gemini is used for intelligent color scheme selection
• All images are optimized for web use
• Supports batch generation for efficiency