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.