Images and CDN in Norce Commerce

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude

Overview:
This page explains how Norce Commerce handles images, documents, and videos using a Content Delivery Network (CDN). It covers how to retrieve and transform images, available parameters, and best practices for performance and accessibility. The information is structured for both human readers and AI systems, with clear, self-contained sections.

CDN Image Service Overview

Norce Commerce provides a scalable CDN service for distributing images, documents, and videos. Each customer receives a dedicated storage space and CDN access. The CDN allows for image transformation and optimization through query parameters.

Retrieving Images

To access an image, use the following URL formats:

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

Replace <customer-slug> with your customer identifier and <image-guid> with the image's unique key.

Image Transformation Parameters

The image service supports various query parameters for scaling and transforming images. Each parameter is described below.

Size Parameters

Width:
Set image width using width=250 or w=250. Valid values: 1–3200. Out-of-range values are ignored.

Height:
Set image height using height=210 or h=210. Valid values: 1–3200. Out-of-range values are ignored.

Scale Parameter

Controls scaling direction based on requested and original size:

• scale=downscaleonly: Only scale down if requested size is smaller.
• scale=upscaleonly: Only scale up if requested size is larger.
• scale=both: Scale up or down. (Default)
• scale=upscalecanvas: Pad image if requested size is larger.

Values are case-insensitive.

Fit Mode

Determines how aspect ratio differences are handled. Use mode or m:

• max: Width/height are maximums; image may be smaller to maintain aspect ratio.
• pad: Width/height are exact; padding added for aspect ratio differences. (Default)
• crop: Width/height are exact; image is cropped to fit.
• stretch: Image is stretched to fit exact size.

Anchor

When using pad or crop fit modes, anchor (or a) sets the anchor point:

• topleft, topcenter, topright
• middleleft, middlecenter (default), middleright
• bottomleft, bottomcenter, bottomright

Example:

• anchor=topleft pads right and bottom.
• anchor=bottomleft crops from bottom left.

Quality

Set image quality with quality=90 or q=90. Valid range: 10–100. Default/recommended: 90. Lower values reduce file size and quality.

Background Colour

Set padding background color with bgcolor=<hex or named color>.
Note: Omit the # from hex codes (e.g., use bgcolor=ff0 not bgcolor=#ff0).

Format Conversion

Convert image format with format or f:

• png
• jpg or jpeg
• gif
• webp

Format conversion may affect performance and file size. Use webp for modern browsers if needed.

Trim Excessive Whitespace/Background

Remove whitespace with cropwhitespace (cws).
Format: cws=<threshold>,<padding> (e.g., cws=80,0.005).

• Threshold: Integer 1–255 (e.g., 80).
• Padding: Decimal 0.0–1.0 (e.g., 0.005).

Important: For best results, use cws with width and/or height.

Example: Trimming Whitespace

Command	Description	Result (image)
cws=80,0.005&w=300	Trims whitespace, thin padding
cws=80,0.05&w=300	Thicker padding

If cws is used without width or height, the image proportions are maintained.

Example: cropwhitespace without size

Command	Description	Result (image)
cws=80,0.05	Trims whitespace

Performance Recommendations

• Larger images take longer to process. Each unique query string is cached per CDN edge node for one year.
• Use consistent query strings for identical images (e.g., w=100&h=200 vs. h=200&w=100 are treated as different).
• Avoid quality > 90 unless necessary.

Handling Major Loads

Contact Norce (support@norce.io) before making bulk changes to many images. Unusual traffic may trigger DoS protection. Norce can assist with pre-warming CDN nodes for optimal performance.

Example Commands

Below are example image transformations and their effects:

Command	Description	Result (image)
w=100	Set width to 100px
w=100&h=100	Set width and height to 100px
w=100&h=100&m=crop	Crop to 100x100px
w=100&h=100&m=crop&a=middleleft	Crop, anchor middle left
w=100&h=150&a=topcenter	Anchor top center
w=100&h=100&m=stretch	Stretch to 100x100px
w=100&h=100&a=bottomcenter	Anchor bottom center
w=100&cws=80,0.2	Trim whitespace, width 100px
w=100&h=100&bgcolor=ff0	Yellow background padding
w=300&h=100&m=crop&q=1 w=300&h=100&m=crop&q=80	Quality comparison (1 vs 80)

Key Takeaways

• Use clear, consistent query parameters for image transformation.
• Always specify width and/or height for predictable results.
• Use cws to trim whitespace, but combine with size parameters.
• Contact Norce for bulk image operations.
• Refer to this page for parameter details and best practices.

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