Apply transformations to asset links

You can apply a variety of on-the-fly transformations to assets by adding transformation parameters to the Get Link APIs or directly to the URL. For example, suppose you generate a link to crop an image to a specific size and want to update it. You can do this by changing the crop region or size directly in the URL.

Link structure

When you create an embed or download link with the transform feature, the generated links are in this format: [Orange Logic domain]-cdn/AssetLink/[KeyForSharedAssets]/[t]/[applied-transform-specification-1]/[applied-transform-specification-2]/[UniqueID].[FileExtension].

For example, suppose you generated a link with these specifications:

• Orange Logic URL: https://mangovations.orangelogic.com
• Transformation 1: Center crop the image to 1000 x 700 pixels
• Transformation 2: Rotate the image by 10 degrees
• Orange Logic Unique ID: CTL675425

Your link will have this structure:

https://mangovations.orangelogic.com/AssetLink/5qd8h7e40r6x2jr087vhm43o860kt8th/t/c\_w\_1000,c\_h\_700,c\_whu\_Pixel,c\_g\_Center/r\_a\_10/CTL675425.jpg

Transformation syntax

Use the syntax described in the following sections to apply transformations to a Get Link API or a URL.

Crop

Apply a crop based on any two of these attributes: width, height, aspect ratio. The crop focuses on the center of the existing image by default. Use either the gravity property or the TopXandTopY properties to choose a different area of focus for your crop.

• Syntax: `c`
• Supported properties: Width, height, aspect ratio, width or height unit, TopX, TopY, gravity, auto crop mode
• Example: Use the following parameters to crop the image to 1000 pixels wide by 675 pixels high. The crop begins 100 pixels down from the top of the image: c\_w\_1000,c\_h\_675,c\_x\_100,c\_y\_0,c\_whu\_pixel\

Crop properties

Width or height unit

• Rules: Use with width or height.
• Syntax: whu\_\[VALUE\]
• Possible values: pixel or percentage (case insensitive)
• Example: `whu_pixel`

TopX and TopY

Together, TopX and TopY determine where to crop an image from. There are two options. You can enter values based on an X-Y pixel grid. For example, an image cropped with the values x_500 and y_600 captures a crop beginning 500 pixels from the left side of the image and 600 pixels from the top of the image. Or, you can enter a float between 0 and 1 to crop the image based on a percentage of its width or height. For example, an image cropped with the values x_0.25 and y_0.5 is cropped from 25% of the left side of the image and 50% of the top of the image.

• Rules: Apply either TopX and TopY together, or use Gravity.
• Syntax: x_[VALUE] or y_[VALUE]
• Value format: A non-negative integer
• Example: x_0, y_200

Gravity

Use the gravity property to determine where to focus a crop, based on a nine-square grid overlaid on the image. The grid labels follow cardinal directions, so the top-left corner is labeled “Northwest.”

• Rules: Apply either TopX and TopY together, or use Gravity.
• Syntax: x_[VALUE]
• Value format: A non-negative integer
• Example: x_0l

Auto crop mode

Select an AI model to determine the focus of the crop. Optical mode is equivalent to the Smart AI mode in the user interface.

• Rules: Apply up to two of the following: width,height, aspect ratio.
• Syntax: acm_[VALUE]
• Possible values:
  • Optical: Orange Logic’s smart crop model
  • SmartSwatch: Used to crop a swatch from an image of fabric
  • GoogleAI
  • AzureAI
• Example: acm_GoogleAI

Resize

Resize the image based on any two of these attributes: width, height, and aspect ratio.

• Syntax: re
• Supported properties: Width, height, aspect ratio, resize method
• Example: Use the following parameters to resize the image to 800 pixels wide by 530 pixels high: re_w_800,re_h_530,re_rm_stretch

Resize method property

This property determines how the image is resized when you specify only width or only height.

• Rules:
  • Fit: The asset is scaled to keep its current aspect ratio, based on the specified measurement.
  • Stretch: The measurement that wasn’t specified (width or height) is retained, and the asset is stretched to fit the new dimensions.
• Syntax: rm_[VALUE]
• Possible values: Fit or Stretch (case insensitive)
• Example: rm_Fit

Crop and resize properties

The following properties can be used when applying a crop or resize transformation.

Width

• Rules: Apply up to two of the following: width,height, aspect ratio. When whu_Percentage is used, the value must be between 0 and 100.
• Syntax: w_[VALUE]
• Value format: A positive integer
• Example: w_500

Height

• Rules: Apply up to two of the following: width,height, aspect ratio. When whu_Percentage is used, the value must be between 0 and 100.
• Syntax: h_[VALUE]
• Value format: A positive integer
• Example: h_500

Aspect ratio

• Rules: Apply up to two of the following: width,height, aspect ratio.
• Syntax: ar_[VALUE]
• Possible values: Use either two positive decimal numbers separated by a colon (16:9) or a positive decimal number (1.7).
• Example: ar_16:9

Rotate

Rotate the image by the number of degrees you specify.

• Syntax: r
• Property: Angle
  • Rules: Use a positive number to rotate clockwise and a negative number to rotate counter-clockwise.
  • Syntax: a_[VALUE]
  • Possible values: A positive or negative number
  • Example value: a_90; a_-90
• Example: Use r_a_10 to rotate the image 10 degrees clockwise.

Quality

Orange Logic uses a quality scale from 0 to 100, where 0 is the most compressed (lowest quality, smallest file) and 100 is not compressed (highest quality; largest file).

• Syntax: q
• Property: Level
• Rule: The quality of the image on an integer scale from 1 (lowest) to 100 (highest).
  • Syntax: level_[VALUE]
  • Possible values: An integer from 1 to 100 (inclusive)
  • Example value: level_75
• Example: Use q_level_75 to compress the image to a quality of 75%.

Metadata

Remove or preserve an image’s metadata. By default, embed and download links remove asset metadata.

• Syntax: fl
• Supported property: Keep
• Example: Use fl_Keep to preserve the image’s metadata.

Update transformations in the URL

You can edit the transformation syntax in the public link URL to apply and edit transformations on-the-fly.

For example, let’s say you start with the following link:

https://mangovations.orangelogic.com/AssetLink/5qd8h7e40r6x2jr087vhm43o860kt8th.jpg

You want to crop this image to a width of 80% with an aspect ratio of 2, focusing on the bottom-right corner. Then, you want to preserve the metadata. Finally, you want to rotate the image 15 degrees to the left. Here is your new URL:

https://mangovations.orangelogic.com/AssetLink/5qd8h7e40r6x2jr087vhm43o860kt8th/t/c\_w\_80,c\_whu\_percentage,c\_ar\_2,c\_g\_Southeast/fl\_keep\_metadata/r\_angle\_-15/.jpg

Example GetLink calls that apply transformations

You can use the Transformations object to apply transformations to a link generated with the GetLink APIs. For example, suppose you want to create a link to an image with the following transformations:

• Resize the asset to 500 px by 500 px, ignoring the aspect ratio.
• Rotate the asset 90 degrees.

To create a link to the transformation for a single image, use this call:

curl -X 'GET' \
  'https://mangovations.com/webapi/objectmanagement/share/getlink_4HZ_v1?Identifier=ZZ111PI&Format=TR1&StickToCurrentVersion=true&LogViews=true&CreateDownloadLink=true&ExpirationDate=2024-12-31T23%3A59%3A59&FileExtension=.jpg&ImageResizingMethod=Stretch&Transformations=re_w_500%2Cre_h_500%2Cr_a_90' \
  -H 'accept: text/plain'

To create links to transformations of multiple images, use this call:

curl -X 'POST' \
  'https://mangovations.com/webapi/objectmanagement/share/getlinks_45W_v1' \
  -H 'accept: text/plain' \
  -H 'Content-Type: application/json-patch+json' \
  -d '{
  "assets": [
    {
      "identifier": "ZZ13GMR",
      "format": "TR1",
      "stickToCurrentVersion": true,
      "logViews": true,
      "createDownloadLink": false,
      "expirationDate": "2024-10-08T03:37:04.831Z",
      "transformations": [
        "re_w_500,re_h_500,re_rm_Stretch",
        "r_a_90"
      ]
     },
        {
      "identifier": "ZZ13F",
      "format": "TR1",
      "stickToCurrentVersion": true,
      "logViews": true,
      "createDownloadLink": false,
      "expirationDate": "2024-10-08T03:37:04.831Z",
      "transformations": [
        "re_w_500,re_h_500,re_rm_Stretch",
        "r_a_90"
      ]
     }
  ],
  "useSession": true
}'