**************************** Vulcan Image Transformations **************************** .. _supported-url-parameters: 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: .. figure:: http://stg-vulcan-api.aws.conde.io/demo/photos/5575d38d1a0272da36c21804/2:1/pass/override.png :align: center 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. .. figure:: http://stg-vulcan-api.aws.conde.io/demo/photos/5575d38d1a0272da36c21804/master/pass/override.png :align: center An image with ``master/pass``, also known as the original image `http://stg-vulcan-api.aws.conde.io/demo/photos/5575d38d1a0272da36c21804/master/pass/override.png `_ 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. .. figure:: http://stg-vulcan-api.aws.conde.io/demo/photos/5575d38d1a0272da36c21804/master/w_100,h_200/override.png :align: center An image at ``w_100,h_200`` `http://stg-vulcan-api.aws.conde.io/demo/photos/5575d38d1a0272da36c21804/master/w_100,h_200/override.png `_ 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. .. figure:: http://stg-vulcan-api.aws.conde.io/demo/photos/5575d38d1a0272da36c21804/master/x_0,y_0,w_100,h_200/override.png :align: center An image with ``x_0,y_0,w_100,h_200`` `http://stg-vulcan-api.aws.conde.io/demo/photos/5575d38d1a0272da36c21804/master/x_0,y_0,w_100,h_200/override.png `_ 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. .. figure:: http://stg-vulcan-api.aws.conde.io/demo/photos/5575d38d1a0272da36c21804/master/w_50,h_100,c_limit/override.png :align: center An image with ``w_50,h_100,c_limit`` `http://stg-vulcan-api.aws.conde.io/demo/photos/5575d38d1a0272da36c21804/master/w_50,h_100,c_limit/override.png `_ .. _famous: http://cloudinary.com/