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

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

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

WARNING

Important: When both w and mw are set, the final image is cropped according to w. Use this combination with care.

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

WARNING

Important: When both h and mh are set, the final image is cropped according to h. Use this combination with care.

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.

Parameter	Type	Default	Allowed Values
extend	boolean	false	1, t, true to enable
gravity	string	ce:0:0	Any 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 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

INFO

Note: Unlike dpr, the zoom option does not affect gravity offsets, watermark offsets, or padding values.

Examples:

# Double the dimensions
z:2

# 1.5x width, 2x 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

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.

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 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

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.

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.

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