contaigents/TEXT_TO_IMAGE_TOOL_GUIDE.md

Modular AI Content Ecosystem with Audio Generation

# TextToImageTool - Complete User Guide

## Overview

The TextToImageTool is a powerful utility that converts text into high-quality images using HTML/CSS templates and browser-based screenshot technology. It supports multiple templates, social media presets, dynamic variables, and custom styling options.

## Features

### ✅ **Core Capabilities**
- **Multiple Templates**: 7 predefined templates for different use cases
- **Social Media Presets**: 7 platform-optimized presets with correct dimensions
- **Dynamic Variables**: JSON-based variable injection for personalized content
- **Custom Styling**: Full control over colors, fonts, dimensions, and CSS
- **High Quality Output**: PNG images with proper anti-aliasing and font rendering
- **Agent Integration**: Works seamlessly with chat agents and tool calls
- **CLI Interface**: Direct command-line access for scripting and automation

### 🎨 **Available Templates**

1. **card** - Social media posts, announcements, quotes with background
2. **banner** - Wide headers, promotional banners, title graphics
3. **quote** - Styled quotations with attribution and decorative elements
4. **code-block** - Syntax-highlighted code snippets with terminal styling
5. **quote-enhanced** - Advanced quotes with author attribution and date support
6. **social-post** - Social media post layout with profile and engagement metrics
7. **certificate** - Professional certificate layout with decorative elements
8. **custom** - Use custom HTML/CSS for complete control

### 📱 **Social Media Presets**

| Preset | Dimensions | Best For |
|--------|------------|----------|
| `instagram-square` | 1080x1080 | Instagram posts |
| `instagram-story` | 1080x1920 | Instagram stories |
| `twitter-post` | 1200x675 | Twitter posts |
| `linkedin-post` | 1200x630 | LinkedIn posts |
| `facebook-cover` | 1200x315 | Facebook cover photos |
| `youtube-thumbnail` | 1280x720 | YouTube thumbnails |
| `pinterest-pin` | 1000x1500 | Pinterest pins |
| `custom` | Variable | LLM-generated templates from descriptions |

## Usage Methods

### 1. CLI Command

```bash
# Basic usage
contaigents text-to-image -t "Hello World!" -o "my_image.png"

# With template and styling
contaigents text-to-image \
  -t "Welcome to Contaigents!" \
  -o "welcome.png" \
  --template "card" \
  --bg-color "#4f46e5" \
  --text-color "#ffffff" \
  --font-size "36"

# Using social media preset
contaigents text-to-image \
  -t "Perfect for Instagram! 📸" \
  -o "insta_post.png" \
  --preset "instagram-square" \
  --bg-color "#e91e63"

# Using custom LLM-generated template
contaigents text-to-image \
  -t "SYNTHWAVE VIBES" \
  -o "retro_poster.png" \
  --preset "custom" \
  --template-prompt "retro 80s synthwave neon poster with purple gradients"

# With variables for enhanced templates
contaigents text-to-image \
  -t "Innovation distinguishes between a leader and a follower." \
  -o "quote.png" \
  --template "quote-enhanced" \
  --variables '{"author": "Steve Jobs", "date": "1997"}'

# List available options
contaigents text-to-image --list-templates
contaigents text-to-image --list-presets
```

### 2. Agent Integration

```
User: Create an Instagram square post with the text "Phase 2 is LIVE! 🚀" using a blue gradient background.

Agent: I'll create an Instagram square post for you with that text and styling.

[Agent makes tool call with preset: "instagram-square"]
```

### 3. Programmatic Usage

```typescript
import { ToolManager } from './services/tools/ToolManager.js';

const toolManager = new ToolManager(process.cwd());

const result = await toolManager.executeTool({
  tool_name: 'text_to_image',
  parameters: {
    text: 'Hello World!',
    output_path: 'output.png',
    template: 'card',
    preset: 'instagram-square',
    background_color: '#4f46e5',
    text_color: '#ffffff'
  }
});
```

## Parameters Reference

### Required Parameters
- **text** (string): Text content to render as image

### Basic Parameters
- **output_path** (string): Output file path (default: "text_image.png")
- **template** (string): Template name (default: "card")
- **width** (number): Image width in pixels (default: 1200)
- **height** (number): Image height in pixels (default: 630)

### Styling Parameters
- **background_color** (string): Background color (default: "#ffffff")
- **text_color** (string): Text color (default: "#000000")
- **font_family** (string): Font family (default: "Arial, sans-serif")
- **font_size** (number): Font size in pixels (default: 24)
- **padding** (number): Content padding in pixels (default: 40)

### Advanced Parameters
- **preset** (string): Social media preset (overrides width/height/template)
- **template_prompt** (string): Template description for custom preset (e.g., "retro 80s neon style")
- **variables** (string): JSON string with template variables
- **custom_html** (string): Custom HTML content (for custom template)
- **custom_css** (string): Additional CSS styles

## Custom Template Generation

### 🤖 **LLM-Powered Templates**
The `custom` preset uses AI to generate unique templates from natural language descriptions:

```bash
contaigents text-to-image \
  -t "Your Text Here" \
  --preset "custom" \
  --template-prompt "describe your desired style here"
```

### **Style Examples**
- **Retro/80s**: "retro 80s synthwave neon poster with purple gradients"
- **Minimal**: "modern minimal clean design with lots of whitespace"
- **Vintage**: "vintage movie poster with aged paper texture"
- **Corporate**: "professional business card with subtle shadows"
- **Artistic**: "watercolor background with hand-drawn elements"

### **How It Works**
1. **LLM Generation**: Attempts to generate HTML/CSS from your description
2. **Smart Fallback**: If LLM fails, uses intelligent rule-based generation
3. **Style Detection**: Analyzes keywords to apply appropriate styling
4. **100% Success**: Always produces a result, even with network issues

## Template Variables

### Common Variables
- **author**: Author name for quotes and certificates
- **date**: Date for quotes and certificates
- **username**: Username for social posts
- **handle**: Social media handle
- **recipient**: Recipient name for certificates
- **authority**: Issuing authority for certificates

### Usage Example
```bash
contaigents text-to-image \
  -t "Advanced AI Development" \
  --template "certificate" \
  --variables '{"recipient": "John Doe", "authority": "Contaigents Academy", "date": "August 2024"}'
```

## Best Practices

### 🎯 **Text Guidelines**
- Keep text concise and readable
- Use appropriate font sizes for target dimensions
- Consider text contrast against background colors
- Break long text into multiple lines

### 🎨 **Design Tips**
- Use high contrast color combinations
- Choose appropriate templates for content type
- Leverage social media presets for platform optimization
- Test different font sizes for readability

### 📐 **Dimension Guidelines**
- **Social Media**: Use presets for platform optimization
- **Banners**: 1920x400 (wide), 1200x300 (standard)
- **Cards**: 800x600 (standard), 600x400 (compact)
- **Certificates**: 1200x900 or larger for print quality

## Examples Gallery

### Basic Card
```bash
contaigents text-to-image -t "Welcome!" --template "card" --bg-color "#3b82f6"
```

### Instagram Story
```bash
contaigents text-to-image -t "New Feature Alert! 🚀" --preset "instagram-story"
```

### Professional Quote
```bash
contaigents text-to-image \
  -t "The future belongs to those who believe in the beauty of their dreams." \
  --template "quote-enhanced" \
  --variables '{"author": "Eleanor Roosevelt", "date": "1945"}'
```

### Code Snippet
```bash
contaigents text-to-image \
  -t "function hello() {\n  console.log('Hello World!');\n}" \
  --template "code-block"
```

## Troubleshooting

### Common Issues

**Error: "Text content cannot be empty"**
- Solution: Ensure the `-t` or `--text` parameter is provided

**Error: "Invalid template"**
- Solution: Use `--list-templates` to see available templates

**Error: "Invalid variables JSON"**
- Solution: Ensure variables parameter is valid JSON string

**Error: "Template not found"**
- Solution: Rebuild the project to ensure templates are copied to dist/

### Performance Tips
- Browser service automatically manages memory and cleanup
- Large images (>2000px) may take longer to generate
- Complex templates with many variables may increase processing time

## Integration Examples

### With Chat Agents
The tool works seamlessly with chat agents. Agents can intelligently choose templates, presets, and styling based on user requests.

### With Scripts
Perfect for automated content generation, social media posting, and batch image creation.

### With Web Applications
Can be integrated into web applications for dynamic image generation.

## Version History

- **Phase 1**: Core functionality with basic templates
- **Phase 2**: Advanced templates, social media presets, dynamic variables
- **Phase 3**: CLI integration, documentation, and polish

## Support

For issues, feature requests, or questions, please refer to the main Contaigents documentation or create an issue in the repository.