Thumb3x Documentation

This component was written to fill a gap in the MODX 3 ecosystem, where modern and reliable tools for working with images are virtually absent. Most existing solutions have not been updated in over 10 years and do not take advantage of the new system version.

Key Features

Modern Formats: On-the-fly conversion to WebP and AVIF.
Advanced Engine: Based on the high-performance Glide 3.0.1 library.
MODX 3 Integration: Full support for Media Sources and System Settings.
Flexible Processing: Filters, effects, watermarks, and precise positioning.
Fenom Support: Convenient snippet calls by passing parameters as arrays.
Cache Management: Logging of generated files in the database with a convenient grid in the manager.

<img src="[[!Thumb3x? &input=`path/to/image.jpg` &options=`w=300&h=200`]]" alt="">

{'!Thumb3x' | snippet : [
    'input' => 'path/to/image.jpg',
    'options' => [
        'w' => 300,
        'h' => 200
    ]
]}

Main Snippet Parameters

Parameter	Alias	Description	Example
`input`	`i`	(Required) Path to the source image.	&input=`image.jpg`
`options`	`o`	String or array (for Fenom) with processing parameters for Glide.	&options=`w=400&fit=crop`
`sourceId`		The Media Source ID for the source image. Defaults to the value from System Settings.	&sourceId=`2`
`watermark`		Path to the watermark file. Activates the watermarking functionality.	&watermark=`assets/logo.png`
`quality`	`q`	(Overridden by `&options`) Default quality.	&quality=`75`
`format`	`fm`	(Overridden by `&options`) Default format.	&format=`webp`

Important: Any parameters (`q`, `fm`, etc.) specified inside the &options string always have the highest priority.

Processing Parameters Reference (`&options`)

Official Glide Documentation

The Thumb3x component uses the Glide library for all image operations. This means you can use any parameter that the library itself supports.

The most complete and up-to-date information on all possible parameters can always be found on the official website:
https://glide.thephpleague.com/

Sizing & Orientation

Parameter	Key	Description	Example
Width	`w`	The width of the output image in pixels.	`w=300`
Height	`h`	The height of the output image in pixels.	`h=200`
Fit	`fit`	How the image is fitted to its target dimensions. Main values: `contain`, `max`, `stretch`, `crop`.	`fit=crop`
Crop	`crop`	Precise cropping: `width,height,x,y`.	`crop=200,150,20,50`
DPR	`dpr`	Device Pixel Ratio. `dpr=2` will return an image twice as large for Retina displays.	`dpr=2`
Orientation	`or`	Rotates the image. Values: `auto`, `0`, `90`, `180`, `270`.	`or=90`
Flip	`flip`	Flips the image. Values: `v` (vertically), `h` (horizontally), `both`.	`flip=h`

Adjustments & Effects

Parameter	Key	Description	Example
Brightness	`bri`	Adjusts brightness (-100 to +100).	`bri=20`
Contrast	`con`	Adjusts contrast (-100 to +100).	`con=-30`
Gamma	`gam`	Gamma correction (0.1 to 9.99).	`gam=2.2`
Sharpen	`sharp`	Sharpens the image (0 to 100).	`sharp=10`
Blur	`blur`	Applies a Gaussian blur (0 to 100).	`blur=15`
Pixelate	`pixel`	Applies a pixelation effect (0 to 1000).	`pixel=10`
Filter	`filt`	Applies a filter: `greyscale` or `sepia`.	`filt=greyscale`

Background & Border

Parameter	Key	Description	Example
Background	`bg`	Sets the background color. Format: `RRGGBB`.	`bg=CCCCCC`
Border	`border`	Adds a border. Format: `width,color,type`. Type: `overlay` or `shrink`.	`border=5,000000,overlay`

Watermarks

Parameter	Key	Description	Example
Path	`mark`	(Required) The watermark's filename.	`mark=logo.png`
Width	`markw`	Watermark width (in px or %).	`markw=15w`
Height	`markh`	Watermark height (in px or %).	`markh=50`
X-Offset	`markx`	Horizontal offset (negative values from the right edge).	`markx=-20`
Y-Offset	`marky`	Vertical offset (negative values from the bottom edge).	`marky=-20`
Padding	`markpad`	Padding on all sides.	`markpad=10`
Position	`markpos`	Position: `top-left`, `center`, `bottom-right`, etc.	`markpos=top-left`
Alpha	`markalpha`	Watermark opacity (0-100).	`markalpha=50`

Output Format

Parameter	Key	Description	Values	Example
Format	`fm`	The output image format.	`jpg`, `png`, `gif`, `webp`, `avif`	`fm=webp`
Quality	`q`	Quality for `jpg`, `webp`, `avif`.	`0` to `100`	`q=80`

Detailed Usage Examples

Example 1: Applying a Watermark (Standard MODX Call)

Task: Apply logo.png to the bottom-right corner with padding and semi-transparency.

<img src="[[!Thumb3x?
    &input=`portfolio/image-01.jpg`
    &watermark=`assets/watermark/logo.png`
    &options=`w=1200&mark=logo.png&markpos=bottom-right&markpad=30&markalpha=50`
]]" alt="Portfolio with watermark">

Example 2: Advanced Fenom Call

Task: Resize the image, crop it to a square, apply a sepia filter, and convert to WebP with 75 quality.

{var $params = [
    'w' => 300,
    'h' => 300,
    'fit' => 'crop',
    'filt' => 'sepia',
    'q' => 75,
    'fm' => 'webp'
]}

<img src="{'!Thumb3x' | snippet : [
    'input' => 'path/to/avatar.jpg',
    'options' => $params
]}" alt="Avatar in sepia">