Images and CDN

Norce Commerce provides a service for scaling and distributing images, documents and videos through a CDN (Content Delivery Network). Each customer is provided a separate storage space and access to CDN.

Getting an image

To retrieve/use an image, the URL format is

• Stage: https://<customer-slug>.stage.cdn-norce.tech/<image guid>?<parameters...
• Production: https://<customer-slug>.cdn-norce.tech/<image guid>?<parameters...

Image transformation

The image service provides a set of options to scale and transform an image. The available directives are:

Size

Width

width=250 or w=250. Valid values are between 1 and 3200. Values outside of this range are ignored (causing the parameter not to be set).

Height

height=210 or h=210. Valid values are between 1 and 3200. Values outside of this range are ignored (causing the parameter not to be set).

Scale

Determine what scaling directions are allowed based on the requested and original image.

scale=<downscaleonly | upscaleonly | both | upscalecanvas>

• downscaleonly: only scale if the requested size is smaller than original.
• upscaleonly: only scale if the requested size is larger than original.
• both: scale both up and down. [Default]
• upscalecanvas: if the requested size is larger than the original, pad the image instead of stretching.

Values are case-insensitive.

Fit mode

How to resolve the aspect ratio when requested size differs from original mode = max | pad | crop | carve | stretch ( m is an alias for mode):

• max: width and height are considered maximum values. The resulting image may be smaller in order to maintain its aspect ratio.
• pad: width and height are considered exact values — padding is used if there's an aspect ratio difference. Use anchor to override middle center default. [Default]
• crop: width and height are considered exact values – cropping is used if there is an aspect ratio difference. Use anchor to override the middle center default.
• stretch: width and height are considered exact values. If there is an aspect ratio difference, the image is stretched.

Values are case-insensitive.

Anchor

Anchor is used when fit mode is pad or crop, and it determines the anchor point of the scaled image. When fit mode pad is used, it determines where the padding occurs. anchor= topleft | topcenter | topright | middleleft | middlecenter [default] | middleright | bottomleft | bottomcenter | bottomright. a can be used as alias for anchor.

• topleft: puts the padding to the right and bottom.
• Using fit mode crop and anchor bottomleft, crops the requested size out from the bottom left corner of the original image.

Values are case-insensitive.

Quality

The image quality setting: quality=90 or q=90. Lower values generate lower resolution/quality but smaller images. Higher generates larger but higher quality images. Valid values are 10–100, 90 is default and recommended.

Background colour

Used to specify other than the default white (#ffffff) background for the padding of images.

bgcolor=<3-digit hex code | 6-digit hex code | html named color>

Format

To convert images to another format, use the format (or f) parameter. Valid target image formats are:

• png
• jpg or jpeg
• gif
• webp

Generally, format conversions are not necessary. There are some use-cases where conversion to webp is good, but format conversions add to the response/conversion time. Conversion to to webp might reduce the image size, but there’s no guarantee, it depends on the format and quality of the original image.

PNG output format is not optimized and will very rarely be a good output format.

Trim excessive whitespace/background

If your images have excessive whitespace/background, it's possible to trim it. This is done by using the cropwhitespace parameter (cws for short). The value is a comma-separated pair <integer>,<decimal> where the integer is the trim threshold (values between 1..255), recommended starting point is 80. The decimal value is the percentage of padding to keep, in percent. Recommended starting point is 0.005.

Example 1,

Command	Original	Result
cws=80,0.005&w=300
cws=80,0.05&w=300 Note the thicker padding

Important Notice, using the cws parameter without a height and/or a width directive may not give the expected result, without any or both of width and/or height, the image proportions will be maintained and

Example 2,

Command	Original	Result
cws=80,0.05

Performance recommendations

• The larger the image is, the longer time the scaling will take. Scaling will only happen once per CDN edge node per year, for each unique image query string.
• Ensure you use the same query string for all images for the same setting. The two requests /abcdef098765fedcba12345?w=100&h=200 and /abcdef098765fedcba12345?h=200&w=100 will generate two scalings.
• Don’t use quality > 90 if it’s not really important – images will retain the necessary quality for screens with quality=90.

Major loads

When doing changes on a large number of images, please contact Norce (support@norce.io) since traffic patterns that deviates too far from normal load can be blocked (DoS protection). Norce can help remove this limitation but also help with pre-warmning the primary CDN edge nodes to maximize performance.

Examples

Command	Result
w=100
w=100&h=100
w=100&h=100&m=crop
w=100&h=100&m=crop&a=middleleft
w=100&h=150&a=topcenter
w=100&h=100&m=stretch
w=100&h=100&a=bottomcenter
w=100&cws=80,0.2
w=100&h=100&bgcolor=ff0
Quality, 1 vs 80. w=300&h=100&m=crop&q=1 w=300&h=100&m=crop&q=80