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):**
   ```bash
   git clone <repository-url>
   cd logo-txt
   ```

2. **Install Python dependencies:**
   ```bash
   pip install -r requirements.txt
   ```
   
   Or with a virtual environment (recommended):
   ```bash
   python3 -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   pip install -r requirements.txt
   ```

3. **Run the application:**
   ```bash
   python app.py
   ```
   
   **For production deployment**, use Gunicorn instead:
   ```bash
   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:**
   ```yaml
   services:
     logo-txt:
       image: ghcr.io/sethwv/logo-txt:latest
       ports:
         - "5001:5001"
       restart: unless-stopped
   ```

2. **Start the application:**
   ```bash
   docker compose up -d
   ```

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

4. **Stop the application:**
   ```bash
   docker compose down
   ```

### Using Docker Run

1. **Pull and run the container:**
   ```bash
   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:**
   ```bash
   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

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

##### Example with Python

```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

```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`:

```yaml
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:

```bash
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:

```bash
# 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:

```yaml
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`:

```yaml
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

```bash
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.