# Resizing & Cropping

This page documents all operations for controlling image dimensions, aspect ratio, cropping, and positioning.

### Resize

```
rs:%resizing_type:%width:%height:%enlarge:%extend
```

The main resizing operation. Combines resizing type, width, height, enlarge, and extend into a single directive. All parameters are optional and can be omitted to use their defaults.

| Parameter      | Type     | Default        | Allowed Values                              |
| -------------- | -------- | -------------- | ------------------------------------------- |
| resizing\_type | string   | `fit`          | `fit`, `fill`, `fill-down`, `force`, `auto` |
| width          | integer  | `0`            | Any positive integer, or `0` for auto       |
| height         | integer  | `0`            | Any positive integer, or `0` for auto       |
| enlarge        | boolean  | `false`        | `1`, `t`, `true` to enable                  |
| extend         | compound | `false:ce:0:0` | See [Extend](#extend)                       |

**Examples:**

```
# Fit within 300x200, keep aspect ratio
rs:fit:300:200

# Fill exactly 400x400, cropping excess
rs:fill:400:400

# Force exact dimensions (may distort)
rs:force:500:300

# Fit within 300x200, allow enlarging small images
rs:fit:300:200:1
```

**Rewrite rule example:**

Regex: `^/thumbnail/(\d+)x(\d+)/(.*)` Target: `/_sx/img/_/rs:fit:$1:$2/q:80/plain/$3`

***

### Size

```
s:%width:%height:%enlarge:%extend
```

Shorthand for width, height, enlarge, and extend — without specifying a resizing type. Uses the current resizing type (default: `fit`).

| Parameter | Type     | Default        | Allowed Values                        |
| --------- | -------- | -------------- | ------------------------------------- |
| width     | integer  | `0`            | Any positive integer, or `0` for auto |
| height    | integer  | `0`            | Any positive integer, or `0` for auto |
| enlarge   | boolean  | `false`        | `1`, `t`, `true` to enable            |
| extend    | compound | `false:ce:0:0` | See [Extend](#extend)                 |

**Example:**

```
s:300:200
```

***

### Resizing Type

```
rt:%resizing_type
```

Defines how smoxy resizes the source image. Can be set independently or as part of the `rs` operation.

| Parameter      | Type   | Default | Allowed Values                              |
| -------------- | ------ | ------- | ------------------------------------------- |
| resizing\_type | string | `fit`   | `fit`, `fill`, `fill-down`, `force`, `auto` |

#### Resizing types explained

| Type        | Behavior                                                                                                                                                      |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `fit`       | Resizes the image to fit entirely within the given dimensions while keeping the aspect ratio. The result will be equal to or smaller than the specified size. |
| `fill`      | Resizes the image to completely fill the given dimensions while keeping the aspect ratio. Parts that extend beyond the target size are cropped.               |
| `fill-down` | Same as `fill`, but if the resized image is smaller than the requested size, it crops the result to maintain the requested aspect ratio.                      |
| `force`     | Resizes to the exact dimensions without keeping the aspect ratio. This may distort the image.                                                                 |
| `auto`      | If both source and result have the same orientation (both portrait or both landscape), uses `fill`. Otherwise, uses `fit`.                                    |

**Example:**

```
rt:fill
```

***

### Width

```
w:%width
```

Sets the width of the resulting image independently. When set to `0`, smoxy calculates the width from the defined height and the source aspect ratio.

| Parameter | Type    | Default | Allowed Values                        |
| --------- | ------- | ------- | ------------------------------------- |
| width     | integer | `0`     | Any positive integer, or `0` for auto |

**Example:**

```
# Resize to 600px wide, height auto-calculated
w:600
```

**Rewrite rule example:**

Regex: `^/w/(\d+)/(.*)` Target: `/_sx/img/_/w:$1/q:80/plain/$2`

A request to `/w/800/media/photo.jpg` resizes the image to 800px width.

***

### Height

```
h:%height
```

Sets the height of the resulting image independently. When set to `0`, smoxy calculates the height from the defined width and the source aspect ratio.

| Parameter | Type    | Default | Allowed Values                        |
| --------- | ------- | ------- | ------------------------------------- |
| height    | integer | `0`     | Any positive integer, or `0` for auto |

**Example:**

```
h:400
```

***

### Min Width

```
mw:%width
```

Defines the minimum width of the resulting image.

| Parameter | Type    | Default | Allowed Values                          |
| --------- | ------- | ------- | --------------------------------------- |
| width     | integer | `0`     | Any positive integer, or `0` to disable |

{% hint style="warning" %}
**Important:** When both `w` and `mw` are set, the final image is cropped according to `w`. Use this combination with care.
{% endhint %}

**Example:**

```
mw:200
```

***

### Min Height

```
mh:%height
```

Defines the minimum height of the resulting image.

| Parameter | Type    | Default | Allowed Values                          |
| --------- | ------- | ------- | --------------------------------------- |
| height    | integer | `0`     | Any positive integer, or `0` to disable |

{% hint style="warning" %}
**Important:** When both `h` and `mh` are set, the final image is cropped according to `h`. Use this combination with care.
{% endhint %}

**Example:**

```
mh:200
```

***

### Enlarge

```
el:%enlarge
```

Controls whether smoxy will enlarge images that are smaller than the target dimensions.

| Parameter | Type    | Default | Allowed Values                                           |
| --------- | ------- | ------- | -------------------------------------------------------- |
| enlarge   | boolean | `false` | `1`, `t`, `true` to enable; `0`, `f`, `false` to disable |

By default, if the source image is smaller than the requested size, smoxy will not upscale it. Enable this option if you need the image to always match the requested dimensions.

**Example:**

```
# Allow enlarging
el:1
```

***

### Extend

```
ex:%extend:%gravity
```

When enabled, if the resized image is smaller than the target dimensions, smoxy pads the canvas to match. The padded area is filled with the [background color](https://docs.smoxy.eu/en/effects-and-adjustments#background).

| Parameter | Type    | Default  | Allowed Values                            |
| --------- | ------- | -------- | ----------------------------------------- |
| extend    | boolean | `false`  | `1`, `t`, `true` to enable                |
| gravity   | string  | `ce:0:0` | Any [gravity](#gravity) value except `sm` |

**Example:**

```
# Extend canvas, place image at top
ex:1:no

# Extend canvas, center the image (default)
ex:1:ce
```

***

### Extend Aspect Ratio

```
exar:%extend:%gravity
```

When enabled, extends the image canvas to match the requested aspect ratio by adding background padding.

| Parameter | Type    | Default  | Allowed Values                            |
| --------- | ------- | -------- | ----------------------------------------- |
| extend    | boolean | `false`  | `1`, `t`, `true` to enable                |
| gravity   | string  | `ce:0:0` | Any [gravity](#gravity) value except `sm` |

**Example:**

```
exar:1:ce
```

***

### Zoom

```
z:%zoom_x_y
z:%zoom_x:%zoom_y
```

Multiplies the image dimensions by the given factor(s). Can be combined with `w` and `h` — smoxy first calculates the size from width/height, then multiplies by the zoom factor.

| Parameter  | Type  | Default | Allowed Values                        |
| ---------- | ----- | ------- | ------------------------------------- |
| zoom\_x\_y | float | `1`     | Any value > 0 (uniform for both axes) |
| zoom\_x    | float | `1`     | Any value > 0                         |
| zoom\_y    | float | `1`     | Any value > 0                         |

{% hint style="info" %}
**Note:** Unlike `dpr`, the `zoom` option does **not** affect gravity offsets, watermark offsets, or padding values.
{% endhint %}

**Examples:**

```
# Double the dimensions
z:2

# 1.5× width, 2× height
z:1.5:2
```

***

### DPR (Device Pixel Ratio)

```
dpr:%dpr
```

Multiplies image dimensions by the given factor for HiDPI (Retina) displays.

| Parameter | Type  | Default | Allowed Values |
| --------- | ----- | ------- | -------------- |
| dpr       | float | `1`     | Any value > 0  |

{% hint style="info" %}
**Note:** Unlike `zoom`, the `dpr` option **does** affect gravity offsets, watermark offsets, and padding values. This ensures that the resulting image structure remains consistent with and without `dpr` applied.
{% endhint %}

**Example:**

```
dpr:2
```

***

### Gravity

```
g:%type:%x_offset:%y_offset
```

Controls where smoxy focuses when cropping parts of the image (used by `fill` resizing, `crop`, and `extend`).

| Parameter | Type   | Default | Allowed Values                          |
| --------- | ------ | ------- | --------------------------------------- |
| type      | string | `ce`    | See table below                         |
| x\_offset | float  | `0`     | Absolute pixels (≥ 1) or relative (< 1) |
| y\_offset | float  | `0`     | Absolute pixels (≥ 1) or relative (< 1) |

#### Gravity types

| Value  | Position                         |
| ------ | -------------------------------- |
| `ce`   | Center (default)                 |
| `no`   | North — top edge                 |
| `so`   | South — bottom edge              |
| `ea`   | East — right edge                |
| `we`   | West — left edge                 |
| `noea` | North-east — top-right corner    |
| `nowe` | North-west — top-left corner     |
| `soea` | South-east — bottom-right corner |
| `sowe` | South-west — bottom-left corner  |

#### Special gravity types

| Value      | Description                                                                                                                                   |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `sm`       | Smart gravity — automatically detects the most "interesting" section of the image and uses it as the center. Offsets are not applicable.      |
| `fp:%x:%y` | Focus point — `x` and `y` are floats between 0 and 1 that define the center of the resulting image. `0:0` is top-left, `1:1` is bottom-right. |

**Examples:**

```
# Crop from the top
g:no

# Crop from bottom-right with 10px offset
g:soea:10:10

# Smart crop
g:sm

# Focus on a point at 30% from left, 70% from top
g:fp:0.3:0.7
```

**Rewrite rule example — smart cropping thumbnails:**

Regex: `^/smart/(\d+)x(\d+)/(.*)` Target: `/_sx/img/_/rs:fill:$1:$2/g:sm/q:80/plain/$3`

***

### Crop

```
c:%width:%height:%gravity
```

Crops the image to specific dimensions **before** resizing. This is useful when you want to extract a specific area from the source image.

| Parameter | Type   | Default             | Allowed Values                                                    |
| --------- | ------ | ------------------- | ----------------------------------------------------------------- |
| width     | float  | required            | Absolute pixels (≥ 1) or relative (0–1). `0` = full source width  |
| height    | float  | required            | Absolute pixels (≥ 1) or relative (0–1). `0` = full source height |
| gravity   | string | uses gravity option | Any [gravity](#gravity) value                                     |

**Examples:**

```
# Crop 500x300 from center
c:500:300:ce

# Crop top-left quadrant (50% of width and height)
c:0.5:0.5:nowe

# Crop 800x600 from top
c:800:600:no
```

***

### Trim

```
t:%threshold:%color:%equal_hor:%equal_ver
```

Removes surrounding background pixels that are similar to a target color. If no color is specified, smoxy auto-detects the background color.

| Parameter  | Type       | Default       | Allowed Values                                                                               |
| ---------- | ---------- | ------------- | -------------------------------------------------------------------------------------------- |
| threshold  | float      | required      | Color similarity tolerance (any positive number)                                             |
| color      | hex string | auto-detected | 6-character hex color without `#` (e.g., `ffffff`). Use `FF00FF` for transparent backgrounds |
| equal\_hor | boolean    | `false`       | `1`, `t`, `true` — trim equal amounts from left and right                                    |
| equal\_ver | boolean    | `false`       | `1`, `t`, `true` — trim equal amounts from top and bottom                                    |

{% hint style="warning" %}
**Important:** Trimming requires the full image to be loaded into memory. This significantly increases memory usage and processing time. Use it carefully with large images. Animated images are not supported.
{% endhint %}

{% hint style="info" %}
**Tip:** If you know the background color of your images, setting it explicitly via the `color` parameter saves resources because smoxy won't need to auto-detect it.
{% endhint %}

**Examples:**

```
# Auto-detect background, threshold 10
t:10

# Trim white background with equal sides
t:10:ffffff:1:1

# Trim transparent background
t:10:FF00FF
```