from unicat import UnicatTransform
We use this on assets, for publishing and/or downloading transformed versions.
transform = UnicatTransform(resize="fill", width=400, height=300, type="jpg", dpr=2, optimize=True)
public_url = asset.publish_transformed(transform)
transform.merge(UnicatTransform(width=200, height=200, key="thumb")) # keeps type, dpr, etc
local_pathname = asset.download_transformed(transform)
A UnicatTransfrom accepts any combination of the following arguments.
name
key
force
optimize
resize
width
height
type
hotspot
crop
padding
quality
background
dpr
Each argument explained:
name = "seo-optimized-name"
Default: use source filename
Use this as the filename instead of the source filename. Mustn't include the extension.
key = "2x"
Default: auto-generate a key from a hash of the options
If you make multiple transforms from the same file, you can use keys to individualize them. They are included in the filename after the name and before the extension. A key is prepended by a '@', so we would get /filename@2x.jpg. You can use @'s in filenames and in keys, just make sure that the combinations add up to a unique final filename.
type = "jpg"
Options: jpg, png, or gif
Both extension and transformed file type. If you don't specify this, the source extension is used, which can lead to faulty results if it isn't one of the supported file types (jpg, png, or gif).
force = True
Default: False
If force isn't enabled, no transformation is done if a file with the transform filename exists and is newer than the source.
optimize = True
Default: False
We support pngcrush, jhead, jpegoptim, jpeg-recompress, gifsicle, scour, and svgo to strip down and compress the transformed file. Since this is a time-consuming process, it is disabled by default.
resize = "fill"
Options: width, height, fit, or fill
Resizing will always respect the aspect ratio. Placement of the resized source on the canvas is controlled by the width, height, hotspot, crop, and padding options. Images are never scaled up, only down.
width = 400
Resulting width of the transformed asset, in logical pixels (see also dpr).
Value is capped at 5000 pixels.
height = 300
Resulting height of the transformed asset, in logical pixels (see also dpr).
Value is capped at 5000 pixels.
hotspot = (0.5, 0.5)
Default: 0.5,0.5 (the center)
The hotspot serves two purposes: first to place the resized image on the canvas with the hotspot as close as possible to the center of the canvas, and second as the centerpoint for the crop transform if one is requested.
The hotspot is given as an x,y coordinate, with values as a fraction of the width and height, respectively. Valid values are 0.0 through 1.0 for each.
crop = (0.6, 0.6)
Default: don't crop
Use crop to select an area from the source that will then be resized to be placed on the canvas. The crop is centered on the hotspot.
The crop is given as w,h dimensions, with values as a fraction of the width and height, respectively. Valid values are 0.0 through 1.0 for each.
padding = (0, "auto", 0, "auto")
Default: auto,auto,auto,auto
Specify padding in the target image. The values are for top, right, bottom, and left padding (clockwise starting at top). If a value is set to auto, that padding will grow to fill available space. If two opposing sides have non-auto values, they will get at least the specified padding, plus half of the remaining available space each. If you want to anchor the image to the top-right of the canvas, you can specify 0,0,"auto","auto".
Values are capped at 1000 pixels.
background = "abcdef"
Default: transparent (or white if transformed file doesn't support transparency)
Specify a background color to use for transparent areas in the source and for any padding added.
There are two predefined options, transparent and white. Any other background color must be specified as an rgb hex value, similar to CSS but without the # sign. Use the full 6-character rgb hex, not a CSS shortcut like bbb.
quality = 82
Default: 100
Lower quality leads to smaller filesizes, but higher quality looks better. This is a compromise, use your best judgment.
Allowed values are 0 through 100.
dpr = 2
Default: 1
Device pixel ratio is abbreviated dpr, and is used to indicate the number of physical pixels the device screen has per logical pixel. You always specify the resizing and padding values in logical pixels. Regular screens have a dpr of 1. High resolution or retina screens have a dpr of 2 or 3. We support a max dpr of 4, just in case. A dpr of 2 means that for a requested width of 400, you get a transformed image with 800 (physical) pixels.
See also the DAM API documentation for transforms for a more detailed explanation.