# Images and CDN in Norce Commerce

**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 | ![Trimmed](https://media.playground.cdn-norce.tech/1000/295addef-c9a8-44bd-8bd6-5737cafbc583?w=300&cws=80,0.005) |
| `cws=80,0.05&w=300` | Thicker padding | ![Thicker](https://media.playground.cdn-norce.tech/1000/295addef-c9a8-44bd-8bd6-5737cafbc583?w=300&cws=80,0.05) |


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 | ![TrimOnly](https://media.playground.cdn-norce.tech/1000/295addef-c9a8-44bd-8bd6-5737cafbc583?cws=80,0.005) |


## 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](https://media.playground.cdn-norce.tech/1000/295addef-c9a8-44bd-8bd6-5737cafbc583?w=100) |
| `w=100&h=100` | Set width and height to 100px | ![w=100 h=100](https://media.playground.cdn-norce.tech/1000/295addef-c9a8-44bd-8bd6-5737cafbc583?w=100&h=100) |
| `w=100&h=100&m=crop` | Crop to 100x100px | ![crop](https://media.playground.cdn-norce.tech/1000/295addef-c9a8-44bd-8bd6-5737cafbc583?w=100&h=100&m=crop) |
| `w=100&h=100&m=crop&a=middleleft` | Crop, anchor middle left | ![crop anchor](https://media.playground.cdn-norce.tech/1000/295addef-c9a8-44bd-8bd6-5737cafbc583?w=100&h=100&m=crop&a=middleleft) |
| `w=100&h=150&a=topcenter` | Anchor top center | ![anchor topcenter](https://media.playground.cdn-norce.tech/1000/295addef-c9a8-44bd-8bd6-5737cafbc583?w=100&h=150&a=topcenter) |
| `w=100&h=100&m=stretch` | Stretch to 100x100px | ![stretch](https://media.playground.cdn-norce.tech/1000/295addef-c9a8-44bd-8bd6-5737cafbc583?w=100&h=100&m=stretch) |
| `w=100&h=100&a=bottomcenter` | Anchor bottom center | ![anchor bottomcenter](https://media.playground.cdn-norce.tech/1000/295addef-c9a8-44bd-8bd6-5737cafbc583?w=100&h=100&a=bottomcenter) |
| `w=100&cws=80,0.2` | Trim whitespace, width 100px | ![cws](https://media.playground.cdn-norce.tech/1000/295addef-c9a8-44bd-8bd6-5737cafbc583?w=100&cws=80,0.2) |
| `w=100&h=100&bgcolor=ff0` | Yellow background padding | ![bgcolor](https://media.playground.cdn-norce.tech/1000/295addef-c9a8-44bd-8bd6-5737cafbc583?w=100&h=100&bgcolor=ff0) |
| `w=300&h=100&m=crop&q=1``w=300&h=100&m=crop&q=80` | Quality comparison (1 vs 80) | ![q=1](https://media.playground.cdn-norce.tech/1000/295addef-c9a8-44bd-8bd6-5737cafbc583?w=300&h=100&m=crop&q=1) ![q=80](https://media.playground.cdn-norce.tech/1000/295addef-c9a8-44bd-8bd6-5737cafbc583?w=300&h=100&m=crop&q=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` |  |