Initial commit

2025-11-30 08:24:18 +08:00
commit b0e1f6dfe3
25 changed files with 6267 additions and 0 deletions
--- a/references/transformation-options.md
+++ b/references/transformation-options.md
@@ -0,0 +1,337 @@
+# Image Transformation Options
+
+Complete reference for all image transformation parameters.
+
+Works with:
+- **URL format**: `/cdn-cgi/image/<OPTIONS>/<SOURCE>`
+- **Workers format**: `fetch(url, { cf: { image: {...} } })`
+
+---
+
+## Sizing
+
+### width
+Max width in pixels.
+
+**URL**: `width=800` or `w=800`
+**Workers**: `{ width: 800 }`
+**Range**: 1-10000
+
+### height
+Max height in pixels.
+
+**URL**: `height=600` or `h=600`
+**Workers**: `{ height: 600 }`
+**Range**: 1-10000
+
+### dpr
+Device pixel ratio for high-DPI displays.
+
+**URL**: `dpr=2`
+**Workers**: `{ dpr: 2 }`
+**Range**: 1-3
+**Example**: `dpr=2` serves 2x size for Retina displays
+
+---
+
+## Fit Modes
+
+### fit
+How to resize image.
+
+**Options**:
+- `scale-down`: Shrink to fit (never enlarge)
+- `contain`: Resize to fit within dimensions (preserve aspect ratio)
+- `cover`: Resize to fill dimensions (may crop)
+- `crop`: Crop to exact dimensions
+- `pad`: Resize and add padding
+
+**URL**: `fit=cover`
+**Workers**: `{ fit: 'cover' }`
+**Default**: `scale-down`
+
+**Examples**:
+```
+fit=scale-down: 800x600 image → max 400x300 → 400x300 (scaled down)
+fit=scale-down: 400x300 image → max 800x600 → 400x300 (not enlarged)
+fit=contain: Any size → 800x600 → Fits inside box, preserves aspect
+fit=cover: Any size → 800x600 → Fills box, may crop edges
+fit=crop: Any size → 800x600 → Exact size, crops as needed
+fit=pad: 800x600 image → 1000x1000 → 800x600 + padding
+```
+
+---
+
+## Quality & Format
+
+### quality
+JPEG/WebP quality.
+
+**URL**: `quality=85` or `q=85`
+**Workers**: `{ quality: 85 }`
+**Range**: 1-100
+**Default**: 85
+**Recommended**: 80-90 for photos, 90-100 for graphics
+
+### format
+Output format.
+
+**Options**:
+- `auto`: Serve AVIF → WebP → Original based on browser support
+- `avif`: Always AVIF (with WebP fallback)
+- `webp`: Always WebP
+- `jpeg`: JPEG (progressive)
+- `baseline-jpeg`: JPEG (baseline, for older devices)
+- `json`: Image metadata instead of image
+
+**URL**: `format=auto` or `f=auto`
+**Workers**: `{ format: 'auto' }`
+**Default**: Original format
+**Recommended**: `format=auto` for optimal delivery
+
+### compression
+WebP compression mode.
+
+**Options**:
+- `fast`: Faster encoding, larger file
+- `lossless`: No quality loss
+
+**URL**: `compression=fast`
+**Workers**: `{ compression: 'fast' }`
+
+---
+
+## Cropping
+
+### gravity
+Crop focal point.
+
+**Options**:
+- `auto`: Smart crop based on saliency
+- `face`: Crop to detected face
+- `left`, `right`, `top`, `bottom`: Crop to side
+- `XxY`: Coordinates (e.g., `0.5x0.5` for center)
+
+**URL**: `gravity=face` or `gravity=0.5x0.3`
+**Workers**: `{ gravity: 'face' }` or `{ gravity: { x: 0.5, y: 0.3 } }`
+**Default**: `auto`
+
+**Examples**:
+```
+gravity=auto: Smart crop to interesting area
+gravity=face: Crop to detected face (if found)
+gravity=0.5x0.5: Center crop
+gravity=0x0: Top-left corner
+gravity=1x1: Bottom-right corner
+```
+
+### zoom
+Face cropping zoom level (when `gravity=face`).
+
+**URL**: `zoom=0.5`
+**Workers**: `{ zoom: 0.5 }`
+**Range**: 0-1
+**Default**: 0
+**Behavior**: `0` = include background, `1` = crop close to face
+
+### trim
+Remove border (pixels to trim from edges).
+
+**URL**: `trim=10`
+**Workers**: `{ trim: 10 }`
+**Range**: 0-100
+
+---
+
+## Effects
+
+### blur
+Gaussian blur radius.
+
+**URL**: `blur=20`
+**Workers**: `{ blur: 20 }`
+**Range**: 1-250
+**Use cases**: Privacy, background blur, LQIP placeholders
+
+### sharpen
+Sharpen intensity.
+
+**URL**: `sharpen=3`
+**Workers**: `{ sharpen: 3 }`
+**Range**: 0-10
+**Recommended**: 1-3 for subtle sharpening
+
+### brightness
+Brightness adjustment.
+
+**URL**: `brightness=1.2`
+**Workers**: `{ brightness: 1.2 }`
+**Range**: 0-2
+**Default**: 1 (no change)
+**Examples**: `0.5` = darker, `1.5` = brighter
+
+### contrast
+Contrast adjustment.
+
+**URL**: `contrast=1.1`
+**Workers**: `{ contrast: 1.1 }`
+**Range**: 0-2
+**Default**: 1 (no change)
+
+### gamma
+Gamma correction.
+
+**URL**: `gamma=1.5`
+**Workers**: `{ gamma: 1.5 }`
+**Range**: 0-2
+**Default**: 1 (no change)
+**Note**: `0` is ignored
+
+---
+
+## Rotation & Flipping
+
+### rotate
+Rotate image.
+
+**Options**: `0`, `90`, `180`, `270`
+
+**URL**: `rotate=90`
+**Workers**: `{ rotate: 90 }`
+
+### flip
+Flip image.
+
+**Options**:
+- `h`: Horizontal flip
+- `v`: Vertical flip
+- `hv`: Both horizontal and vertical
+
+**URL**: `flip=h`
+**Workers**: `{ flip: 'h' }`
+
+**Note**: Flipping is performed BEFORE rotation.
+
+---
+
+## Other
+
+### background
+Background color for transparency or padding.
+
+**URL**: `background=rgb(255 0 0)` (CSS4 syntax)
+**Workers**: `{ background: 'rgb(255 0 0)' }`
+**Examples**:
+- `background=white`
+- `background=rgb(255 255 255)`
+- `background=rgba(255 255 255 50)`
+
+**Use with**: `fit=pad` or transparent images (PNG, WebP)
+
+### metadata
+EXIF metadata handling.
+
+**Options**:
+- `none`: Strip all metadata
+- `copyright`: Keep only copyright tag
+- `keep`: Preserve most EXIF metadata
+
+**URL**: `metadata=keep`
+**Workers**: `{ metadata: 'keep' }`
+**Default**: `copyright` for JPEG, `none` for others
+
+**Note**: Color profiles and EXIF rotation always applied, even if metadata stripped.
+
+### anim
+Preserve animation frames (GIF, WebP).
+
+**URL**: `anim=false`
+**Workers**: `{ anim: false }`
+**Default**: `true`
+
+**Use case**: Converting animated GIF to still image
+
+---
+
+## Combining Options
+
+**URL Format**:
+```
+/cdn-cgi/image/width=800,height=600,fit=cover,quality=85,format=auto/image.jpg
+```
+
+**Workers Format**:
+```javascript
+fetch(imageURL, {
+  cf: {
+    image: {
+      width: 800,
+      height: 600,
+      fit: 'cover',
+      quality: 85,
+      format: 'auto'
+    }
+  }
+});
+```
+
+---
+
+## Common Presets
+
+### Thumbnail
+```
+width=300,height=300,fit=cover,quality=85,format=auto
+```
+
+### Avatar
+```
+width=200,height=200,fit=cover,gravity=face,quality=90,format=auto
+```
+
+### Hero
+```
+width=1920,height=1080,fit=cover,quality=85,format=auto
+```
+
+### Blur Placeholder (LQIP)
+```
+width=50,quality=10,blur=20,format=webp
+```
+
+### Product Image
+```
+width=800,height=800,fit=contain,sharpen=2,quality=90,format=auto
+```
+
+### Responsive (Mobile)
+```
+width=480,quality=85,format=auto
+```
+
+### Responsive (Tablet)
+```
+width=768,quality=85,format=auto
+```
+
+### Responsive (Desktop)
+```
+width=1920,quality=85,format=auto
+```
+
+---
+
+## Limits
+
+- **Max dimensions**: 10,000 x 10,000 pixels
+- **Max area**: 100 megapixels
+- **Max file size**: No published limit (but 10MB recommended)
+- **Quality range**: 1-100
+- **DPR range**: 1-3
+
+---
+
+## Official Documentation
+
+- **Transform via URL**: https://developers.cloudflare.com/images/transform-images/transform-via-url/
+- **Transform via Workers**: https://developers.cloudflare.com/images/transform-images/transform-via-workers/