cloudinary-transformations

What this skill does

# Cloudinary Transformation Rules

## When to Use

- Building Cloudinary delivery/transformation URLs
- Converting natural language requests to transformation syntax
- Debugging transformation URLs that aren't working
- Optimizing images or videos with Cloudinary
- Applying effects, overlays, resizing, or cropping

## Quick Start

### Default Best Practice: Always Optimize

**Add `f_auto/q_auto` to the end of nearly every transformation URL** (as final components):
- Automatically delivers optimal format
- Optimizes quality for best balance of visual quality and file size
- Reduces bandwidth and improves performance

**Example:** `c_fill,g_auto,w_400,h_300/f_auto/q_auto`

**Exceptions - Don't add optimization when:**
- Account has "Optimize By Default" enabled (already applied automatically)
- Special quality requirements (use `q_auto:best`, `q_auto:low`, or manual `q_N` instead)
- Specific format required (replace `f_auto` with `f_png`, `f_jpg`, etc.)
- Delivering exact original with no modifications

**Examples of common transformations (with optimization):**
1. Resize: `c_scale,w_400/f_auto/q_auto`
2. Smart crop: `c_fill,g_auto,h_300,w_400/f_auto/q_auto`
3. Background removal: `e_background_removal/f_png/q_auto`
4. Text overlay: `co_yellow,l_text:Arial_40:Hello%20World/fl_layer_apply,g_south/f_auto/q_auto`
5. Image overlay: `l_logo/c_scale,w_100/fl_layer_apply,g_north_west,x_10,y_10/f_auto/q_auto`

**Important:** All transformation strings shown throughout this skill are illustrative examples to demonstrate syntax and concepts. When generating transformations, choose specific values (dimensions, colors, positions, etc.) based on the user's actual requirements and use case, not the example values shown.

**For debugging:** See [references/debugging.md](references/debugging.md) for detailed troubleshooting steps.


## Gathering Requirements

Before generating a transformation URL, if not already specified, clarify these details based on the user's request:

### For Resize/Crop Requests
**Required:**
- At least one dimension (width OR height)
- Crop behavior if both dimensions specified (fill, pad, scale, limit, etc.)

**Clarify:**
- Focal point/gravity (especially for cropping): Face detection? Center? Smart auto-detection?
- Maintain aspect ratio? (if only one dimension, this is automatic)

**Example questions:**
- "What dimensions do you need? (width and/or height)"
- "Should this fill the space (may crop) or fit within it (no cropping)?"
- "Any important focal point? (faces, center, specific area)"

### For AI Transformation Requests
**Background removal:**
- Output format needs (PNG for transparency vs JPG with solid background)
- What to do with transparent area (keep transparent, add color, or gen_fill)

**Generative fill:**
- Target dimensions or aspect ratio
- How much extension needed

**Generative replace:**
- What object to replace (from)
- What to replace it with (to)
- Preserve original shape? (for clothing/objects)

**Generative remove:**
- What object(s) to remove
- Remove all instances or just one?

**Generative background replace:**
- Describe desired background (or use auto-generation)
- Need reproducibility? (consider seed parameter)

### For Video Transformation Requests
**Trimming:**
- Start and end time, or duration
- Seconds or percentage of video

**Codec/format:**
- Output format needs (MP4, WebM, etc.)
- Quality requirements (use `vc_auto` if unsure)

**Audio:**
- Keep or remove audio track
- If for autoplay, suggest removing audio (`ac_none`)

### Always Recommend
Unless user specifies otherwise:
- **Add `f_auto/q_auto` at the end** of transformation URLs (see Quick Start section for exceptions)
- Use `g_auto` for smart cropping when filling dimensions
- Consider cost for AI transformations (inform user of transformation credits)

## Quick Reference

### URL Structure

```
https://res.cloudinary.com/<cloud_name>/<asset_type>/<delivery_type>/<transformations>/<version>/<public_id>.<ext>
```

**Key Rules:**
- Commas (`,`) separate parameters **within** a component
- Slashes (`/`) separate components **between** transformations
- Each component acts on the output of the previous one

### Parameter Types

**Action parameters**: Perform transformations (one action per component: each action transformation should be separated by a slash)
**Qualifier parameters**: Modify action behavior (in the same component as the action, using commas as separators)

Check the [Transformation Reference](https://cloudinary.com/documentation/transformation_reference.md) to determine if a parameter is an action or qualifier.

## Core Transformations

### Resize & Crop

**Dimension value formats:**
- **Whole numbers** (e.g., `w_400`, `h_300`) = pixels
- **Decimal values** (e.g., `w_0.5`, `h_1.0`) = percentage of original dimensions (0.5 = 50%, 1.0 = 100%)

**Choosing the right crop mode:**

Use **`c_scale`** when:
- Resizing while maintaining original aspect ratio
- Specify only ONE dimension (width OR height)
- No cropping needed
- The user intentionally wants to stretch or squash an image by changing the aspect ratio

Use **`c_fill`** when:
- Must fit exact dimensions (e.g., thumbnail grid, fixed layout)
- Okay to crop parts of image
- Combine with `g_auto` for smart cropping, or `g_face` for portraits

Use **`c_fit`** when:
- Image must fit within dimensions without cropping
- Okay to have empty space
- Maintaining full image content is critical

Use **`c_pad`** when:
- Must fit exact dimensions without cropping
- Need to fill empty space with background color/blur/AI-generated pixels
- Use with `b_<color>` or `b_auto` (blurred background) or `b_gen_fill`

Use **`c_limit`** when:
- Set maximum dimensions but don't upscale small images
- Preserving original quality of small images matters

Use **`c_thumb`** when:
- Creating thumbnails (typically avatars)
- Use with `g_face` for face-centered crops

Use **`c_auto`** when:
- Cloudinary should intelligently crop to interesting content
- Combine with `g_auto` for best results
- Good for dynamic content where focal point varies

**Examples:**
```
c_scale,w_400                      # Resize width to 400px, maintain aspect ratio
c_scale,w_0.5                      # Resize to 50% of original width
c_fill,g_auto,h_300,w_400          # Fill 400x300px dimensions, smart crop
c_fit,h_300,w_400                  # Fit within dimensions, no crop
c_pad,b_white,h_300,w_400          # Pad to exact size with white background
c_pad,w_1.0                        # Pad to original width (100%)
c_limit,w_1000                     # Limit max width, no upscale
c_thumb,g_face,h_150,w_150         # Face-centered square thumbnail
c_auto,g_auto,w_800                # Auto crop to interesting area
```

**Important**: Always specify a crop mode explicitly. Avoid using both dimensions with `c_scale` (will distort if aspect ratios don't match) - prefer one dimension to maintain aspect ratio.

### Gravity (Focal Point)

Gravity determines which part of the image to focus on when cropping:

- **`g_auto`** - Smart detection (recommended for varied content; detects faces, objects, contrast)
- **`g_face`** - Face detection (portraits, avatars)
- **`g_center`** - Center position (centered subjects, logos)
- **`g_north`, `g_south_east`, etc.** - Compass positions (fixed locations, overlay positioning)
- **`x_N,y_N`** - Custom offsets (integers = pixels, floats = percentage: 0.8 = 80%)

**Examples:**
```
c_fill,g_auto,w_400,h_300                      # Smart crop
c_thumb,g_face,w_200,h_200                     # Face-centered
l_logo/fl_layer_apply,g_south_east,x_10,y_10  # Logo bottom-right
```

**Important**: 
- `g_auto` only works with `c_fill`, `c_lfill`, `c_crop`, `c_thumb`, `c_auto`
- When using x, y, h, w together, use all integers OR all floats (don't mix)

### Format & Quality

**Recommended defaults:**
- **`f_auto/q_auto`** - Use for most production images (WebP to supported browsers, optimized file size)

**Specific formats**