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.

Tip

Use the local Docker server on port 8080 for the examples in this chapter.

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(width=300, height=300, mode='fill'),  # 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(width=300, height=300, mode='fill'),
    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 use different settings, create a new transformation.

Compose transformations¶

Group related settings in separate transformations, then unpack their options to combine them. You can add more options to the result:

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 reusable groups of processing options.
base = Transform(quality=85, format='webp')
square = Transform(Resize(width=300, height=300, mode='fill'))

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

# Add a higher pixel density to the combined options.
retina = Transform(*thumbnail.options, dpr=2)

# Build URLs using the composed transformations.
thumbnail_url = client.url(source=source_url, transform=thumbnail)
retina_url = client.url(source=source_url, transform=retina)

print(thumbnail_url)
print(retina_url)

thumbnail combines the quality and format from base with the crop from square. retina uses the same options with twice the pixel density. Each composition creates a new transformation; the original transformations remain unchanged.

Unpacking appends options without merging or replacing them. Keep shared groups focused on different settings to avoid conflicting options.

Next steps¶

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