Vulcan Image Transformations¶
Supported URL parameters¶
Vulcan currently only supports a very small subset of the parameters found on other very famous sites, with very similar syntax.
Aspect ratios are specified in the format
{width}:{height}
or, alternatively, master to specify “whatever the original is”.
Note
Vulcan does not reduce aspect ratios! For example, 4:4 is treated as a different aspect ratio than 1:1. End-users should reduce aspect ratios passed into Vulcan URls to increase the client-side cache-ability of images by reducing the different ways the same image can be requested.
Note
Clips have the following “aspect ratios”:
- 1080p
- 720p
- 360p
- original completely untranscoded original file
Parameters are specified with a comma-separated set of tokens in the format
{key}_{value}
{key} will be 1-2 letters.
The following is supported:
| key | valid values | behavior |
w |
A positive integer | Used for cropping/resizing. The desired width of the image, or the width of the bounding box you want to scale the image to fit into. |
h |
A positive integer | Used for cropping/resizing. The desired height of the image, or the width of the bounding box you want to scale the image to fit into. |
x |
A positive integer | Used for cropping. The x coordinate that represents where
the upper left corner of the crop is. If specified,
y, w, and h are required. |
y |
A positive integer | Used for cropping. The y coordinate that represents where
the upper left corner of the crop is. If specified,
x, w, and h are required. |
c |
limit |
Used when resizing. Disables skewing or stretching of the image. |
restrictCropping images¶
Images which have a restrictCropping: true flag set on the root of the
payload will not be croppable, but can be resized.
override images¶
Like restrictCropping images, images which come from the API with an
override: true field for a particular aspect ratio cannot be re-cropped, but
can be resized.
This flag is set when a user overrides an aspect ratio manually, with another physical image.
The logic is that if the user manually overrides a particular crop, the resulting overridden image is assumed to be exactly what they want.
Aspect ratios¶
Specifying master in the {aspectRatio} section of the url indicates the
original image, whatever aspect ratio it may be.
If an aspect ratio has not been defined in the configuration for the API, Vulcan will try to generate an image of that particular aspect ratio by cropping around the top-center of the image. For example:
An image with aspect ratio 2:1, which has NOT been defined in the API’s config
The pass parameter¶
In order to specify no modifications to the image, and, therefore, simply proxy
through the image at the specified aspect ratio, you can use the word pass
in the transformations section of the url.
Therefore, specifying master/pass will simply proxy back the original image.
An image with master/pass, also known as the original image
Resizing¶
When w_... and/or h_... are specified (without x and y), the
image will be forcibly resized to the specified dimensions, skewing and
stretching the image if necessary.
This behavior can be disabled using the c_... parameter.
If you specify only one, the image will be resized preserving aspect ratio until to that specification.
Cropping¶
When x_... and y_... are specified (and therefore also w and h),
the coordinates + width/height specified are used to create a crop of the image.
An image with x_0,y_0,w_100,h_200
Resize restrictions¶
Specifying c_limit will prevent the image from skewing or resizing. This
means that the resulting image may not be the exact dimensions you specified.
For example, for a 100x100 px image, specifying h_50,w_70,c_limit will
return an image of size 50x50 px, because it’s the largest image that fits
within the bounding box.
The image will also not be stretched, meaning, for a 100x100 px image,
specifying h_500,w_500,c_limit will return the original image at 100x100 px.
An image with w_50,h_100,c_limit