mirror of
https://github.com/Theodor-Springmann-Stiftung/kgpz_web.git
synced 2025-10-30 17:45:30 +00:00
130 lines
4.0 KiB
Markdown
130 lines
4.0 KiB
Markdown
# Image Compression System
|
|
|
|
This system provides automatic dual image loading for optimal performance:
|
|
|
|
- **Layout views**: Compressed WebP images for fast browsing
|
|
- **Single page viewer**: Full-quality JPEG images for detailed reading
|
|
|
|
## File Structure
|
|
|
|
```
|
|
pictures/
|
|
├── 1771-42-166.jpg # Original high-quality image
|
|
├── 1771-42-166-preview.webp # Compressed preview for layouts
|
|
├── 1771-42-167.jpg # Original high-quality image
|
|
├── 1771-42-167-preview.webp # Compressed preview for layouts
|
|
└── ...
|
|
```
|
|
|
|
## How It Works
|
|
|
|
### Backend (Go)
|
|
- `ImageFile` struct includes both `Path` (original) and `PreviewPath` (compressed)
|
|
- Image registry automatically detects `-preview.webp` files during initialization
|
|
- Templates receive both paths for each image
|
|
|
|
### Frontend (Templates)
|
|
- Layout views use `<picture>` elements with WebP source and JPEG fallback
|
|
- Single page viewer uses `data-full-image` attribute to load full-quality images
|
|
- Automatic fallback to original image if preview doesn't exist
|
|
|
|
### Performance Benefits
|
|
- **60-80% smaller file sizes** for layout browsing
|
|
- **Additional 75% size reduction** from 50% resize for preview images
|
|
- **Faster page loads** with compressed and resized images
|
|
- **Full quality** maintained for detailed viewing
|
|
- **Progressive enhancement** with WebP support detection
|
|
|
|
## Generating WebP Previews
|
|
|
|
### Automatic Generation
|
|
Run the provided script to convert all existing images:
|
|
|
|
```bash
|
|
./scripts/generate_webp_previews.sh
|
|
```
|
|
|
|
### Manual Generation
|
|
For individual files:
|
|
|
|
```bash
|
|
# The script automatically calculates 50% dimensions
|
|
cwebp -q 75 -m 6 -resize 1200 800 pictures/1771-42-166.jpg -o pictures/1771-42-166-preview.webp
|
|
```
|
|
|
|
### Quality Settings
|
|
- **Quality**: 75% (good balance for text-heavy images)
|
|
- **Compression**: Level 6 (maximum compression)
|
|
- **Resize**: 50% (reduces file size by ~75% additionally)
|
|
- **Format**: WebP (excellent text preservation)
|
|
|
|
## Browser Support
|
|
|
|
### WebP Support
|
|
- Chrome/Edge: ✅ Full support
|
|
- Firefox: ✅ Full support
|
|
- Safari: ✅ Full support (14+)
|
|
- Fallback: Automatic JPEG fallback for older browsers
|
|
|
|
### Picture Element
|
|
- Modern browsers: ✅ Optimal WebP loading
|
|
- Older browsers: ✅ Automatic JPEG fallback
|
|
- No JavaScript required
|
|
|
|
## File Size Comparison
|
|
|
|
Typical compression results for newspaper images:
|
|
|
|
| Image Type | Original JPEG | WebP Preview (50% + compression) | Total Savings |
|
|
|------------|---------------|----------------------------------|---------------|
|
|
| Text page | 800 KB | 80 KB | 90% |
|
|
| Mixed page | 1.2 MB | 120 KB | 90% |
|
|
| Image page | 1.5 MB | 190 KB | 87% |
|
|
|
|
## Development Notes
|
|
|
|
### Template Usage
|
|
```html
|
|
<picture>
|
|
{{- if ne $page.PreviewPath "" -}}
|
|
<source srcset="{{ $page.PreviewPath }}" type="image/webp">
|
|
{{- end -}}
|
|
<img src="{{ if ne $page.PreviewPath "" }}{{ $page.PreviewPath }}{{ else }}{{ $page.ImagePath }}{{ end }}"
|
|
data-full-image="{{ $page.ImagePath }}"
|
|
alt="Page {{ $page.PageNumber }}" />
|
|
</picture>
|
|
```
|
|
|
|
### JavaScript Integration
|
|
```javascript
|
|
// Single page viewer automatically uses full-quality image
|
|
const fullImageSrc = imgElement.getAttribute('data-full-image') || imgElement.src;
|
|
viewer.show(fullImageSrc, ...);
|
|
```
|
|
|
|
### Fallback Strategy
|
|
1. **Missing preview**: Uses original JPEG
|
|
2. **WebP unsupported**: Browser loads JPEG fallback
|
|
3. **File not found**: Standard error handling
|
|
|
|
## Monitoring
|
|
|
|
### Check Compression Status
|
|
```bash
|
|
# Count preview files
|
|
find pictures -name "*-preview.webp" | wc -l
|
|
|
|
# Compare total sizes
|
|
find pictures -name "*.jpg" -exec du -ch {} + | tail -1
|
|
find pictures -name "*-preview.webp" -exec du -ch {} + | tail -1
|
|
```
|
|
|
|
### Regenerate Previews
|
|
```bash
|
|
# Regenerate all previews
|
|
./scripts/generate_webp_previews.sh
|
|
|
|
# Force regeneration (remove existing previews first)
|
|
find pictures -name "*-preview.webp" -delete
|
|
./scripts/generate_webp_previews.sh
|
|
``` |