Relatude has an advanced URL-based image transformation engine built-in. It works equally well in .Net or in headless scenarios.
Basics
Images are stored in either a file folder or a file property in Relatude. Both the inner content object in the file folder and the file property exposes a FilePropertyValue. A FilePropertyValue object has a GetUrl() method. If you don't specify a parameter, it returns the original file.
If property contains an image, you can use a number of overloads to the GetUrl method to transform the image. The most used and most basic transformation is to resize the image refered to in the FilePropertyValue. The following code resizes the image to a picture with width of 400px and height of 300px:
devArt.IngressPicture.GetUrl(400, 300);
If you want to scale to same width, but different height, depending on the aspect ratio of the picture, you can supply the width only:
devArt.IngressPicture.GetUrl(400);
How it works
The systems generates images as they are requested, based on the url. The first time a unique url is received, the Image transformation engine converts the original image based on the parameters in the url. The C# api generates a url based on the parameters sent to the GetUrl method.
After the image has been transformed according to the url parameters, the scaled image based on that one specific url is cached on disk, and will never be regenerated for requests with the same parameters.
More advanced uses
While resizing images is the most common operation done, the api supports a number of different other operations as well. While there are several different overloads, we recommend that you use the ImageAdjustments object as a parameter to the GetUrl method if you need to specify more than width and height.
There are also convenience methods like GetImageHtml, that creates an image tag around the generated url. It supports the same parameters as the GetUrl method.
The following code generates a circular image with a width and height of 300px:
var devArt = WAFContext.Request.GetContent<DeveloperArticle>();
ImageAdjustments adjust = new ImageAdjustments();
adjust.CanvasX = 300;
adjust.CanvasY = 300;
adjust.CornerRadius = 150;
var url = devArt.IngressPicture.GetUrl(adjust);
ImageAdjustments properties
| Property name | Url parameter | Description |
|---|
| CanvasX |
x |
The width of the scaled image |
| CanvasY |
y |
The height of the scaled image |
| CornerRadius |
corner |
The number of pixels the corner should use to round the image. If set to 50% of the width and height, it will return a circular image. |
| BorderWidth |
border |
The width of the border around the image |
| Zoom |
z |
The zoom factor |
| CanvasXMobile |
xm |
The width on mobile |
| CanvasYMobile |
ym |
The height on mobile |
| OffsetX |
ox |
The X offset |
| OffsetY |
oy |
The Y offset |
| Brightness |
b |
The brightness of the image (0-100) |
| Contrast |
c |
The contrast of the image (0-100) |
| Saturation |
s |
The saturation of the image (0-100) |
| Quality |
q |
The quality of the resized image (if applicable) |
| ZoomMode |
zm |
Which ZoomMode should be used:
- Fill (default), makes sure the specified rectangle (implicit or explicit) is filled by the image
- Fit. Makes sure the whole image fits inside the rectangle. If the aspect ratio is different between the original and the scaled image, this will result in either the top and bottom or left and right side will have bars in the color of the specified background color.
- Carving: Uses Seam Carving to transform the image. Analyzes the image to get the important areas of the image, and preserve them when resizing the image.
|
| BackgroundColor |
bgc |
The background color of the image. Mostly used with Fit ZoomMode, where the image in many situations doesn't fill the specified rectangle. |
| HorizontalFocusShift |
fx |
Where in the image the focus point is set (horizontally) |
| VerticalFocusShift |
fy |
Where in the image the focus point is set (vertically) |
| Resolution |
dpi |
The resolution of the scaled image |
| HorizontalResolution |
dpix |
The horizontal resolution of the scaled image |
| VerticalResolution |
dpiy |
The vertical resolution of the scaled image |
Headless usage
Since the C# api generates a url string, this can easily be created manually in headless mode. The headless api's return the original file url's. Add the url parameters you need(from the list above) to the original url to generate the images you need.
To notify the transformation engine to adjust the image, you also need to specify a "adjust=1" parameter in the url