logo-txt/README.md

📺 Logo Text Adder

A Python web application for adding custom text to TV station and network logos. Upload a logo, specify your text and positioning preferences, and download the enhanced image with expanded canvas.

Features

• 🎨 Web Interface: User-friendly web UI for easy logo processing
• 🔌 REST API: Programmatic access for automation
• 📐 Flexible Positioning: Add text above, below, left, or right of logos
• 🎨 Customization: Adjust font size, text color, background color, and padding
• 📦 Multiple Formats: Supports PNG, JPG, JPEG, GIF, and WEBP
• ⚡ Instant Preview: See results immediately in the browser

Quick Start

Using Python Directly

If you prefer to run the application without Docker:

1. Clone the repository (or download the files):

   git clone <repository-url>
   cd logo-txt
   

2. Install Python dependencies:

   pip install -r requirements.txt
   

   Or with a virtual environment (recommended):

   python3 -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   pip install -r requirements.txt
   

3. Run the application:

   python app.py
   

   For production deployment, use Gunicorn instead:

   gunicorn --bind 0.0.0.0:5001 --workers 4 app:app
   

4. Access the application: Open your browser and navigate to http://localhost:5001

5. Stop the application: Press Ctrl+C in the terminal

Using Docker Compose (Recommended)

1. Create a docker-compose.yml file:

   services:
     logo-txt:
       image: ghcr.io/sethwv/logo-txt:latest
       ports:
         - "5001:5001"
       restart: unless-stopped
   

2. Start the application:

   docker compose up -d
   

3. Access the application: Open your browser and navigate to http://localhost:5001

4. Stop the application:

   docker compose down
   

Using Docker Run

1. Pull and run the container:

   docker run -d -p 5001:5001 --name logo-txt ghcr.io/sethwv/logo-txt:latest
   

2. Access the application: Open your browser and navigate to http://localhost:5001

3. Stop the container:

   docker stop logo-txt
   docker rm logo-txt
   

Usage

Web Interface

1. Open your browser and navigate to http://localhost:5001
2. Upload your logo image or enter an image URL
3. Enter the text you want to add
4. Choose the position (above, below, left, or right)
5. Optionally adjust advanced settings:
   • Font (default: auto - automatically detects best match)
   • Font size (default: auto - scales based on image size)
   • Padding (default: auto - scales based on font size)
   • Text color (default: white)
   • Background color (default: transparent)
6. Click "Generate Logo"
7. Preview and download your enhanced logo
8. Copy the API URL shown below the preview to use the same settings programmatically

API Usage

The application provides a REST API endpoint for programmatic access.

Process Image from URL

GET /api/image

Process an image from a URL using query parameters. The image is returned directly.

Query Parameters

• url (string, required): URL of the image to process
• text (string, required): Text to add to the image
• position (string, optional): Where to place the text (above, below, left, or right) - default: below
• font_size (integer or "auto", optional): Font size in pixels, or "auto" for automatic sizing - default: auto
• font_path (string, optional): Path to a specific font file to use, or "auto" for automatic detection - default: auto
• text_color (string, optional): Text color - default: white
• bg_color (string, optional): Background color or "transparent" - default: transparent
• padding (integer or "auto", optional): Padding in pixels or "auto" - default: auto

Example URLs

Basic usage:

http://localhost:5001/api/image?url=https://example.com/logo.png&text=Breaking%20News

With all parameters:

http://localhost:5001/api/image?url=https://example.com/logo.png&text=Breaking%20News&position=below&font_size=auto&text_color=white&bg_color=transparent&padding=auto

Example with cURL

curl "http://localhost:5001/api/image?url=https://example.com/logo.png&text=Breaking%20News&position=below" \
  --output processed_logo.png

Example with Python

import requests

url = "http://localhost:5001/api/image"
params = {
    "url": "https://example.com/logo.png",
    "text": "Breaking News",
    "position": "below",
    "font_size": "auto",
    "text_color": "white",
    "bg_color": "transparent"
}

response = requests.get(url, params=params)

if response.status_code == 200:
    with open("processed_logo.png", "wb") as f:
        f.write(response.content)
    print("Image processed successfully!")
else:
    print(f"Error: {response.json()}")

Example with JavaScript

const params = new URLSearchParams({
    url: 'https://example.com/logo.png',
    text: 'Breaking News',
    position: 'below',
    font_size: 'auto',
    text_color: 'white',
    bg_color: 'transparent'
});

const response = await fetch(`http://localhost:5001/api/image?${params}`);

if (response.ok) {
    const blob = await response.blob();
    const url = URL.createObjectURL(blob);
    // Use the URL to display or download the image
} else {
    const error = await response.json();
    console.error('Error:', error);
}

Project Structure

logo-txt/
├── app.py                 # Flask application and image processing logic
├── templates/
│   └── index.html        # Web interface
├── uploads/              # Temporary storage for uploaded images (auto-created)
├── requirements.txt      # Python dependencies
├── Dockerfile            # Docker image configuration
├── docker-compose.yml    # Docker Compose configuration
└── README.md            # This file

How It Works

1. Image Upload: User uploads a logo through the web interface or API
2. Canvas Expansion: The application calculates the required canvas size based on text dimensions and position
3. Text Rendering: Text is rendered with the specified styling on the expanded canvas
4. Image Composition: The original logo and text are composited onto the new canvas
5. Output: The processed image is returned to the user for download

Configuration

Environment Variables

The application supports the following environment variables for controlling functionality:

• ENABLE_UI (default: true)

  • Set to false to disable the web interface
  • Useful for API-only deployments
  • Accepted values: true, false, 1, 0, yes, no, on, off
  • Example: ENABLE_UI=false

• ENABLE_API (default: true)

  • Set to false to disable all API endpoints
  • Useful for UI-only deployments or security requirements
  • Accepted values: true, false, 1, 0, yes, no, on, off
  • Example: ENABLE_API=false

Using with Docker Compose

Add environment variables to your docker-compose.yml:

services:
  logo-txt:
    image: ghcr.io/sethwv/logo-txt:latest
    ports:
      - "5001:5001"
    environment:
      - ENABLE_UI=true
      - ENABLE_API=true
    restart: unless-stopped

Using with Docker Run

Pass environment variables with the -e flag:

docker run -d -p 5001:5001 \
  -e ENABLE_UI=true \
  -e ENABLE_API=false \
  --name logo-txt \
  ghcr.io/sethwv/logo-txt:latest

Using with Python Directly

Set environment variables before running the application:

# Linux/macOS
export ENABLE_UI=true
export ENABLE_API=true
python app.py

# Windows (Command Prompt)
set ENABLE_UI=true
set ENABLE_API=true
python app.py

# Windows (PowerShell)
$env:ENABLE_UI="true"
$env:ENABLE_API="true"
python app.py

Docker Configuration

The application runs on port 5001 by default. To change the port, modify the docker-compose.yml file:

ports:
  - "8080:5001"  # Maps host port 8080 to container port 5001

Application Settings

You can modify these settings in app.py:

• MAX_CONTENT_LENGTH: Maximum upload file size (default: 16MB)
• UPLOAD_FOLDER: Temporary folder for uploads (default: 'uploads')
• Server host and port in the if __name__ == '__main__' block

Note: The built-in Flask development server (python app.py) is not suitable for production. For production deployments:

• Docker (recommended): Uses Gunicorn automatically with 4 workers
• Manual deployment: Use gunicorn --bind 0.0.0.0:5001 --workers 4 app:app
• Adjust --workers based on available CPU cores (recommended: 2-4 × CPU cores)
• Increase --timeout for processing large images (default in Docker: 120 seconds)

Troubleshooting

Port Already in Use

If port 5001 is already in use, change the port mapping in docker-compose.yml:

ports:
  - "8080:5001"  # Use port 8080 instead

Then access the application at http://localhost:8080

Font Issues

The Docker image includes DejaVu and Liberation fonts by default. If you need additional fonts, you can:

1. Modify the Dockerfile to install additional font packages
2. Mount a font directory as a volume in docker-compose.yml

View Container Logs

docker compose logs -f

License

This project is provided as-is for personal and commercial use.

Contributing

Feel free to submit issues, fork the repository, and create pull requests for any improvements.