Image scaling and distribution

Richie offers facilities for caching and serving processed and optimized images, with originals hosted on the web.

The images can be resized, cropped and watermarked, if necessary. The original and resulting images are cached to minimize traffic. The resulting images are optimized for minimum download size, while maintaining a high level of visual quality.

Source images are either fetched from an origin agreed in the setup phase, or alternatively using encrypted URLs requested from a dedicated API endpoint.

Setup and some limitations

To use images endpoints, contact Richie for setup. To start using encrypted URLs, you will receive credentials. To start using clear URLs, you will need to provide an origin URL to which source image URLs are relative.

Fully supported source file formats are GIF, JPEG, PNG, WEBP and BMP. SVG is cached and served without processing.

Output format can be agreed when configuring the service, or it can be set for individual requests.

It is also possible to declare a watermark scheme, which means agreeing to draw other images and rectangles on top of source images. The method for requesting watermarks is different for clear relative and encrypted URLs. When using encrypted URLs, non-tamperable watermarks are requested at encryption time. If it is not necessary to protect watermark from tampering, watermarks can also be requested when requesting the image. When using clear relative URLs, the watermarks are always requested with the image request.

Endpoints

Encryption API

Encrypted image URLs are requested from Encryption API. You will provide clear URLs and whether you want to use non-tamperable watermarks, and Encryption API will return distributable public URLs to the images on Richie CDN. It is also possible to receive feature detection based center points at this phase.

You will need to provide your credentials in HTTP Basic Authorization scheme to use Encryption API.

Input for Encryption API is a JSON document with the following keys. All are optional. Meaningful use will require at least one URL, though.

Non-tamperable watermarks are requested during the encryption phase. If a watermark scheme is requested at the encryption phase, the query parameter wm in the resulting image URL must be included in all image requests. If the parameter is missing or it has been altered, Images API will refuse to serve the image.

Property	Description	Value
urls	Clear image source URLs to encrypt	List of URLs
asset_urls	Clear asset source URLs to encrypt	List of URLs
include_thumbnail_crop	Whether to include feature detection based crop boxes for images	true or false
watermark_scheme	Watermark scheme name to apply and protect	Watermark scheme name

Example request document:

{
    "include_thumbnail_crop": true,
    "urls": [
        "https://images.example.com/800x1800.jpg"
    ],
    "watermark_scheme": "logos"
}

Response JSON document will contain encrypted URLs for all the images and possibly crop boxes.

{
    "processedURLs": {
        "https://picsum.photos/800/1900?random=1": {
            "encrypted_url": "https://data.richie.app/images/v1/TestTenant/lAR0J4vb-8SWaouf3R5zSPKmxmDrZakksuOg2h4RBpRR984D4dx-fjwDMo3Auac?wm=logos",
            "properties": {
                "height": 800,
                "width": 1800
            },
            "thumbnail_crop": {
                "center_x": 0,
                "center_y": 0.6
            }
        }
    }
}

Images API

End users request images from the Images API. Images API is the frontend for serving cached and processed images. The target width and height, result image format and the strategy (mode) to achieve those is specified as query parameters to the Image API.

Image API responds with the processed image ready for display.

Images, other than SVG, can be processed in three different modes. "Fit" will resize the image below the requested dimensions in a bounding box, maintaining the aspect ratio. "Stretch" will change the aspect ratio to fit the requested dimensions exactly, unless source image is smaller. "Crop" will extract an area of the image by either following center_x and center_y parameters, and if they are not set, AI feature detection is performed to find the most interesting part of the image.

SVG images are not processed. GIF and PNG source images requested in GIF or PNG are not processed. These requests are responded to with the source file.

PNG encoded to WEBP is losslessly encoded regardless of the quality setting.

Images are never scaled up.

Source image location is declared in the query path, either as encrypted or relative to the previously agreed origin. All parameters are set in the query string and are optional.

Property	Description	Value
width	Fit the image to this width	Targeted width, positive integer
height	Fit the image to this height	Targeted height, positive integer
dpr	Apply a multiplier to width, height and size to convert between physical and logical pixels on a HiDPI device	Device pixel ratio, positive integer
mode	Select how the image is processed to fit the new dimensions. Also set both width and height, if using "crop" or "stretch" here.	"fit", "stretch" or "crop"
center_x	Specify a center point for a cropped image with this and center_y	Decimal number between 0.0 and 1.0. Horizontal center point relative to image width.
center_y	Specify a center point for a cropped image with this and center_x	Decimal number between 0.0 and 1.0. Vertical center point relative to image height.
size	Fit both dimensions of the image to the same size. A shortcut for width=height=size and mode=fit.	Maximum width and height as a positive integer
quality	Set quality parameter for JPEG and WEBP encoders	Integer between 0 and 100
format	Encode the result in this image format	"jpeg", "png" or "webp"
wm	Use watermarks according to a scheme	Watermark scheme name (tamper-proof when used with encryption)
ol	Use watermarks ("overlay") according to a scheme	Watermark scheme name (not protected from tampering)

Example URL (clear with a relative origin): https://data.richie.app/images/v1/TestTenant/2a48f17.jpg?width=450&height=642&dpr=1&mode=fit