338 lines
6.4 KiB
Markdown
338 lines
6.4 KiB
Markdown
# 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/
|