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

client = Client('http://localhost:8080')
source_url = 'https://picsum.photos/id/237/1600/1200'

thumbnail = Transform(
    Resize.fill(width=300, height=300),  # (1)!
    quality=85,  # (2)!
    format='webp',
)

thumbnail_url = client.url(source=source_url, transform=thumbnail)

print(thumbnail_url)

Pass structured processing options as positional option instances.
Pass scalar options as keywords. quality=85 is equivalent to Quality(85).

Show Output

http://localhost:8080/unsafe/resize:fill:300:300/quality:85/format:webp/aHR0cHM6Ly9waWNzdW0ucGhvdG9zL2lkLzIzNy8xNjAwLzEyMDA

Pass thumbnail to client.url() to apply it to an image. See Options for available options and their arguments.

Reuse a transformation¶

Define a transformation once and use it with different source images:

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

client = Client('http://localhost:8080')
thumbnail = Transform(  # (1)!
    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, sep='\n')

Transformations and built-in options are immutable. You can keep thumbnail at module level and reuse it across requests.

Show Output

http://localhost:8080/unsafe/resize:fill:300:300/format:webp/aHR0cHM6Ly9waWNzdW0ucGhvdG9zL2lkLzIzNy8xNjAwLzEyMDA
http://localhost:8080/unsafe/resize:fill:300:300/format:webp/aHR0cHM6Ly9waWNzdW0ucGhvdG9zL2lkLzEwMjUvMTYwMC8xMjAw

Each URL uses the same transformation with a different source.

Compose transformations¶

Use extend() to create a new transformation with additional options:

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

client = Client('http://localhost:8080')
source_url = 'https://picsum.photos/id/237/1600/1200'

base = Transform(quality=85, format='webp')  # (1)!

thumbnail = base.extend(Resize.fill(width=300, height=300))  # (2)!

retina = thumbnail.extend(dpr=2)  # (3)!

print('Base:', client.url(source_url, transform=base))
print('Thumbnail:', client.url(source_url, transform=thumbnail))
print('Retina:', client.url(source_url, transform=retina))

Shared quality and output format.
Append a square crop, leaving base unchanged.
Append a pixel density option, leaving thumbnail unchanged.

Show Output

Base: http://localhost:8080/unsafe/quality:85/format:webp/aHR0cHM6Ly9waWNzdW0ucGhvdG9zL2lkLzIzNy8xNjAwLzEyMDA
Thumbnail: http://localhost:8080/unsafe/quality:85/format:webp/resize:fill:300:300/aHR0cHM6Ly9waWNzdW0ucGhvdG9zL2lkLzIzNy8xNjAwLzEyMDA
Retina: http://localhost:8080/unsafe/quality:85/format:webp/resize:fill:300:300/dpr:2/aHR0cHM6Ly9waWNzdW0ucGhvdG9zL2lkLzIzNy8xNjAwLzEyMDA

The generated URLs show the options retained by each transformation. New positional options follow existing options; scalar keywords come last, in keyword order.

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

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

client = Client('http://localhost:8080')
source_url = 'https://picsum.photos/id/237/1600/1200'

base = Transform(quality=85, format='webp')
square = Transform(Resize.fill(width=300, height=300))

thumbnail = base.extend(*square.options)  # (1)!

print(client.url(source_url, transform=thumbnail))

Unpack square.options to append its options to base. Both original transformations remain unchanged.

Show Output

http://localhost:8080/unsafe/quality:85/format:webp/resize:fill:300:300/aHR0cHM6Ly9waWNzdW0ucGhvdG9zL2lkLzIzNy8xNjAwLzEyMDA

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.