# pyPhotoAlbum

![Test Coverage](https://gitea.tourolle.paris/dtourolle/pyPhotoAlbum/raw/branch/badges/cov_info/coverage.svg)
![Documentation Coverage](https://gitea.tourolle.paris/dtourolle/pyPhotoAlbum/raw/branch/badges/cov_info/coverage-docs.svg)
![License](https://img.shields.io/badge/license-MIT-blue.svg)

A desktop application for designing and creating professional photo albums with an intuitive drag-and-drop interface and high-quality PDF export.

## Overview

pyPhotoAlbum is a photo album design tool built with PyQt6 and OpenGL, offering a powerful yet user-friendly interface for creating custom photo layouts. It supports drag-and-drop image placement, template-based designs, and high-quality PDF export.

## Key Features

- **Visual Editor**: OpenGL-accelerated rendering with real-time preview
- **Drag & Drop**: Direct image import from file explorer
- **Template System**: Create and reuse page layouts
- **Smart Layout Tools**: Alignment, distribution, and sizing operations
- **Asset Management**: Automatic image organization with reference counting
- **Project Files**: Save/load projects in portable ZIP format (.ppz)
- **PDF Export**: High-quality export with configurable DPI
- **Undo/Redo**: Complete command history for all operations
- **Double-Page Spreads**: Design facing pages for book-style albums

## Installation

### Quick Install (Linux)

```bash
# Clone the repository
git clone https://gitea.tourolle.paris/dtourolle/pyPhotoAlbum.git
cd pyPhotoAlbum

# Run automated installer
./install.sh
```

**For detailed instructions:** See [INSTALLATION.md](INSTALLATION.md)

### Distribution Packages

**Fedora (RPM):**
```bash
rpmbuild -ba pyphotoalbum.spec
sudo dnf install ~/rpmbuild/RPMS/noarch/pyphotoalbum-*.rpm
```

**Arch/CachyOS (PKGBUILD):**
```bash
makepkg -si
```

See [INSTALLATION.md](INSTALLATION.md) for complete instructions.

## Quick Start

### Running the Application

After installation, launch pyPhotoAlbum:

```bash
pyphotoalbum
```

Or run directly from source:

```bash
python pyPhotoAlbum/main.py
```

### Basic Workflow

1. **Create a New Project** - Choose your page size (A4, Letter, etc.) and DPI
2. **Add Pages** - Start with blank pages or use templates
3. **Add Images** - Drag and drop images from your file browser onto pages
4. **Arrange & Edit** - Move, resize, rotate, and crop images to your liking
5. **Save Your Work** - Projects are saved as .ppz files (ZIP archives)
6. **Export to PDF** - Generate high-quality PDFs ready for printing

## Using Templates

pyPhotoAlbum includes a template system to help you quickly create consistent layouts:

- **Built-in Templates**: Grid layouts, single large image, and more
- **Custom Templates**: Save your favorite layouts as templates
- **Flexible Application**: Apply templates to new or existing pages

## Architecture Highlights

pyPhotoAlbum is built with clean, maintainable design patterns:

### Mixin-Based Composition

The main OpenGL widget is composed of **12 specialized mixins** instead of one monolithic class:
- Each mixin handles a single responsibility (viewport, rendering, selection, etc.)
- Average ~90 lines per mixin for maintainability
- Easy to test in isolation with comprehensive unit tests
- Clean separation of concerns throughout the codebase

### Declarative UI with Decorators

The ribbon interface is **auto-generated from decorator metadata**:
- `@ribbon_action` - Automatically creates ribbon buttons from method metadata
- `@undoable_operation` - Automatically captures state for undo/redo
- `@dialog_action` - Separates dialog presentation from business logic
- No manual UI wiring required - just add decorators to your methods

This approach keeps UI concerns separate from business logic and makes the codebase easier to maintain and extend.

## Keyboard Shortcuts

- `Ctrl+Z` - Undo
- `Ctrl+Y` - Redo
- `Ctrl+S` - Save project
- `Ctrl+O` - Open project
- `Ctrl+N` - New project
- `Ctrl+E` - Export to PDF
- `Delete` - Delete selected element
- `Arrow Keys` - Move selected element
- `Shift+Arrow Keys` - Resize selected element
- `Ctrl+D` - Duplicate selected element

## License

This project is licensed under the MIT License.

## Acknowledgments

Built with:
- PyQt6 for the GUI framework
- OpenGL for hardware-accelerated rendering
- ReportLab for PDF generation
- Pillow for image processing