CaribouPDF

A Go application for converting images to PDF and CBZ files with automatic double-page detection for magazines and comics.

Features

• Automatic Double-Page Detection: Detects magazine-style double-page spreads by aspect ratio and automatically splits them into facing pages
• Drag & Drop Interface: Intuitive file and folder handling with visual feedback
• Smart Output Naming: Auto-generates output filenames based on source content
• Progress Tracking: Real-time conversion progress with cancellation support
• Multiple Formats: Supports JPEG, PNG, GIF, BMP, TIFF, and WebP images
• Linux Native: Built for Linux environments with native system integration
• Version Tracking: Build version includes git commit hash for traceability

Magazine-Style PDF Generation

CaribouPDF automatically detects double-page spreads (wide images with aspect ratio > 1.3) and converts them to proper facing pages:

• Single pages (ratio ≤ 1.3): Creates one standard PDF page
• Double spreads (ratio > 1.3): Splits into two facing pages for magazine layout
• Smart layout: Works with PDF viewers like Okular in "facing pages" mode

Perfect for creating PDFs from magazines, comics, and scanned books!

Documentation

• Installation Guide - System requirements and setup
• User Guide - How to use the application
• API Reference - Function documentation and data structures
• Architecture - Code structure and design decisions
• Development - Contributing and building from source
• Troubleshooting - Common issues and solutions

Quick Start

# Clone and build
git clone <repository-url>
cd cariboupdf
./scripts/build.sh

# Run the application
./bin/cariboupdf

Drag images or folders onto the window to start converting.

Example Usage:

# Single folder (current behavior)
./run.sh /path/to/magazine

# Batch processing (experimental) 
./run.sh batch /path/to/magazines
# Drop multiple folders → create multiple PDFs automatically

🔧 Development Tools:

# Build with debug output
go build -o bin/cariboupdf main.go

# Run with debug
./run.sh -debug

# Test batch processing
./run.sh batch

• Double spreads: Pages 1, 4, 25, 53 (1.41 aspect ratio → 2 facing pages each)
• Single pages: All other content (0.71 aspect ratio → 1 page each)
• Result: Perfect magazine layout in PDF viewers with facing pages enabled

Setup

Prerequisites

1. Go (1.19 or later)
2. GUI development libraries (required for Fyne)

Linux (Fedora/CentOS/RHEL)

sudo dnf install libX11-devel libXcursor-devel libXrandr-devel libXi-devel mesa-libGL-devel libXinerama-devel

Linux (Ubuntu/Debian)

sudo apt-get install libgl1-mesa-dev libx11-dev libxcursor-dev libxrandr-dev libxinerama-dev libxi-dev

macOS

xcode-select --install

Windows

Install MinGW-w64 or TDM-GCC for development headers.

Installation

# Clone and setup
git clone <repository-url>
cd cariboupdf

# Install dependencies
./scripts/install.sh

# Build the application
./scripts/build.sh

# Or use Makefile
make build

Usage

# Run the application
./scripts/run.sh

# Or using Makefile
make run

Design

This application follows a strict late-80s/early-90s IBM utility aesthetic:

• Fixed window size: 420×380
• IBM beige color palette
• No animations, gradients, or shadows
• Flat, functional interface
• Explicit visual hierarchy

Scripts

• ./scripts/install.sh - Install all dependencies
• ./scripts/build.sh - Build the application
• ./scripts/run.sh - Run the application
• make - Alternative build system with targets: build, run, install, clean

Color Palette

• Cream Main: #E6E1D6
• Cream Inset: #E3DDCF
• Ink Primary: #1E1F22
• Ink Soft: #2A2B2F