134 lines
4.3 KiB
Markdown
134 lines
4.3 KiB
Markdown
# pyPhotoAlbum
|
|
|
|
|
|
|
|
|
|
|
|
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
|