Transform¶

A Transform defines how imgproxy should process an image, including its dimensions, quality, and output format. Pass it to Client when building a URL, and reuse the same transformation across different source images.

Create a transformation¶

Pass structured options as positional arguments and simple settings as keyword arguments:

from imgproxykit import Client, Transform
from imgproxykit.options import Resize

# Public URL of your imgproxy server.
client = Client('http://localhost:8080')
source_url = 'https://picsum.photos/id/237/1600/1200'

# Define the thumbnail dimensions, quality, and output format.
thumbnail = Transform(
    Resize.fill(width=300, height=300),  # Pass typed option objects.
    quality=85,  # Or scalar keywords, equivalent to Quality(85).
    format='webp',
)

# Build the URL; imgproxy processes the image when the URL is requested.
thumbnail_url = client.url(source=source_url, transform=thumbnail)

print(thumbnail_url)

thumbnail combines a 300×300 crop, quality 85, and WebP output format. Pass it to client.url() through the transform argument and open the printed URL to see the result. The Options chapter explains the available option classes and their arguments.

Reuse a transformation¶

Transformations are immutable and designed for reuse. Define a transformation once and use it for different source images; building a URL does not change its settings. Built-in option instances are immutable too.

For example, reuse a 300×300 WebP thumbnail transformation across product images:

from imgproxykit import Client, Transform
from imgproxykit.options import Resize

client = Client('http://localhost:8080')
# Reuse the same transformation for multiple source images.
thumbnail = Transform(
    Resize.fill(width=300, height=300),
    format='webp',
)

source_urls = [
    'https://picsum.photos/id/237/1600/1200',
    'https://picsum.photos/id/1025/1600/1200',
]
thumbnail_urls = [
    client.url(source=source_url, transform=thumbnail)
    for source_url in source_urls
]

print(thumbnail_urls)

thumbnail_urls contains a URL for each source, using the same crop and format. You can keep thumbnail at module level and reuse it across requests. To add processing options, create a new transformation with extend(), as shown below.

Compose transformations¶

Use extend() to create a new transformation with additional options. It accepts the same positional options and scalar keyword arguments as the constructor:

from imgproxykit import Transform
from imgproxykit.options import Resize

# Share quality and output format across transformations.
base = Transform(quality=85, format='webp')

# Add a square crop without changing the base transformation.
thumbnail = base.extend(Resize.fill(width=300, height=300))

# Create a higher pixel density version of the thumbnail.
retina = thumbnail.extend(dpr=2)

Each call returns a new transformation, leaving the original unchanged. New positional options follow the existing options; scalar keyword options come last, in keyword order.

To combine reusable groups, pass another transformation’s unpacked options to extend():

from imgproxykit import Transform
from imgproxykit.options import Resize

# Define reusable groups of processing options.
base = Transform(quality=85, format='webp')
square = Transform(Resize.fill(width=300, height=300))

# Combine options from both transformations.
thumbnail = base.extend(*square.options)

extend() appends options without merging or replacing them. For example, base.extend(quality=70) retains both quality options. Imgproxy resolves the resulting settings and determines the processing pipeline.

Next steps¶

Continue with Options to explore processing options and their values. See the Transform API reference for all transformation arguments.