Panorama Album Generator

A CLI utility to generate panoramic photo album websites from 360° images.

This tool takes a directory of high-resolution 360° panoramic images, optimizes them for web viewing, generates thumbnails, and creates a complete interactive photo album website with a modern design.

Features

• 🖼️ Automatic Image Processing: Scales and converts panoramic images to WebP format for optimal web performance
• 🎯 Smart Thumbnails: Generates appropriately sized thumbnails with automatic naming
• 🎨 Modern Design: Beautiful, responsive photo album interface with glassmorphism effects
• 🌐 Interactive Panorama Viewer: Uses Pannellum.js for immersive 360° viewing experience
• ⚡ Optimized Performance: Lazy loading, progressive enhancement, and optimized file formats
• 📱 Responsive Design: Works beautifully on desktop, tablet, and mobile devices
• ♿ Accessible: Keyboard navigation support and screen reader friendly

Prerequisites

• Python 3.12+
• UV package manager

Installation

1. Clone or download this project
2. Dependencies are already configured in pyproject.toml and will be installed automatically

Usage

Basic Usage

Generate a panorama album from a source directory:

uv run pano-album --source-dir ./my-panoramas --output-dir ./my-album --album-name "My Virtual Tour"

Command Line Options

• --source-dir, -s: Source directory containing panoramic images (required)
• --output-dir, -o: Output directory for the generated website (required)
• --album-name, -n: Name/title for the photo album (required)
• --web-scale: Scale percentage for web images (default: 60)
• --thumb-scale: Scale percentage for thumbnails (default: 12)
• --quality: WebP quality for processed images (default: 85)
• --verbose, -v: Enable verbose output
• --version: Show version information
• --help: Show help message

Example with Custom Settings

uv run pano-album \
  --source-dir ./360-photos \
  --output-dir ./virtual-tour \
  --album-name "Office Virtual Tour" \
  --web-scale 70 \
  --thumb-scale 15 \
  --quality 90 \
  --verbose

Directory Structure

After running the generator, your output directory will contain:

my-album/
├── index.html          # Main gallery page
├── view.html           # Panorama viewer page
├── pannellum.js        # Panorama viewer library
├── pannellum.css       # Viewer styles
└── images/
    ├── image1.webp     # Web-optimized panoramas
    ├── image1-t.webp   # Thumbnails
    ├── image2.webp
    ├── image2-t.webp
    └── ...

Supported Image Formats

• JPEG (.jpg, .jpeg)
• PNG (.png)
• WebP (.webp)
• BMP (.bmp)
• TIFF (.tif, .tiff)

Customizing Captions

After generation, you can edit the captions by modifying the generated index.html file. Look for instances of "Replace with Caption" and update them with your desired descriptions.

Advanced Configuration

The utility provides sensible defaults that match the workflow described in your PRD:

• Web images: 60% scale, WebP format, quality 85
• Thumbnails: 12% scale, WebP format, quality 85, with "-t" suffix
• Modern color theme: Dark gradients with coral accent colors
• Responsive design: Mobile-first approach with progressive enhancement

Development

To work on this project:

1. Install Dependencies:

uv sync

2. The project structure:

pano-album/
├── pano_album/         # Main package
│   ├── __init__.py
│   └── main.py         # CLI implementation
├── templates/          # Jinja2 templates
│   └── index.html
├── assets/            # Static assets
│   ├── view.html
│   ├── pannellum.js
│   └── pannellum.css
├── scale_images.py    # Image processing utility
└── pyproject.toml     # Project configuration

Example Workflow

1. Take 360° panoramic photos with your camera
2. Place them in a source directory (e.g., ./source/)
3. Run the generator:

   uv run pano-album -s ./source -o ./my-tour -n "My Amazing Tour"

4. Open ./my-tour/index.html in a web browser
5. Edit captions in the HTML file as needed
6. Deploy to your web server or host locally

Tips

• Image Quality: Start with high-resolution source images for best results
• Performance: The default 60%/12% scaling provides a good balance of quality and file size
• Captions: Use descriptive captions to help users navigate your virtual tour
• Testing: Always test on multiple devices and browsers
• Hosting: The generated site is fully static and can be hosted anywhere

Troubleshooting

• "No images found": Ensure your source directory contains supported image formats
• "scale_images.py not found": Make sure you're running from the project root directory
• UV command not found: Install UV package manager: curl -LsSf https://astral.sh/uv/install.sh | sh
• Permission errors: Check that you have write access to the output directory

License

This project uses the Pannellum panorama viewer library, which is licensed under the MIT License.

---

Legacy scale_images.py Script Notes

The underlying image processing is handled by scale_images.py. For manual use:

• Scale images by 60% with WebP conversion: uv run scale_images.py --percent 60 --input-dir images --output-dir images-scaled --to-webp --quality 85
• The script preserves EXIF orientation and runs in parallel for speed
• Use --optimize for format-specific lossless compression
• Use --strip-metadata to remove EXIF/ICC metadata for smaller files