Add transformations to assets

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.

(Beta) You can also generate composite images by overlaying images (such as logos, watermarks, badges, and other images) onto a base image. For example, suppose you want to generate various product photo variations for a social media campaign. You can use a base photo and generate a hero image with a "home for the holidays" campaign badge pinned to the top-right corner at 90% opacity. Or, you might generate crops for social media posts co-branded with multiple logos. You can also overlay product photos on top of lifestyle images. Each transformation is generated from a single source asset and has a distinct URL. Users can change the URL on the fly, reducing load time and maintaining visibility into asset performance from links delivered through a CDN.

ℹ️

Note

Support for image overlays is available for beta testing beginning in Orange Logic Queenstown.

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.

Brightness

Brighten or darken the image.

• Rules: Enter a number between -100 (darkest) and 100 (brightest). The default is 0, which keeps the image brightness as is.
• Syntax: brightness_v_[VALUE] or o_v_[VALUE]
• Possible values: pixel (case insensitive)
• Example: br_v_50

ℹ️

Note

The brightness transformation is available beginning in Orange Logic Queenstown.

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 (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: g_[VALUE]
• Value format: A non-negative integer
• Example: g_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

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

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.

Opacity

Set the transparency.

• Rules: Enter a decimal between 0.0 (fully transparent) and 1.0 (fully opaque).
• Syntax: opacity_v_[VALUE] or o_v_[VALUE]
• Possible values: pixel (case insensitive)
• Example: o_v_0.5

ℹ️

Note

The opacity transformation is available beginning in Orange Logic Queenstown.

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

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%.

Add layers

You can generate composite images by overlaying images (such as logos, watermarks, badges, and other images) onto a base image. Use the l_image_[ID] syntax where the ID for the overlay image is one of the following asset IDs:

• The asset key generated when you create an embed link
• The unique ID . You can use the unique ID only if the overlay is already public, meaning the everyone group (both registered and unregistered) users have permission to view the original asset View original permission.

You can add transformations to the overlay with the standard transformation syntax (resize, crop, etc.), and you can adjust the placement of the overlay by configuring the layer’s properties , including the gravity, anchor, offset, and overflow behavior.

You can apply various sets of transformations in a single URL:

• Overlay an image using an embed URL with existing transformations.
• Add transformations to the base image and the overlay.
• Add multiple overlays on a single base image.
• Add nested overlays.

ℹ️

Notes

You can only overlay images that are stored in the Orange Logic platform. You cannot overlay external images.
The opacity transformation is available beginning in Orange Logic Queenstown.

Layer properties

All layer properties use the l_ prefix.

Gravity and anchor

Gravity represents where on the base image the layer is placed. The anchor represents the point on the layer image that aligns to the gravity point. The gravity and anchor are both centered by default.

• Gravity syntax: l_gravity_[VALUE] or l_g_[VALUE]
• Anchor syntax: l_anchor_[VALUE] or l_an_[VALUE]
• Gravity example: l_g_se
• Anchor example: l_an_sw

Gravity and anchor

Gravity represents where on the base image the layer is placed. The anchor represents the point on the layer image that aligns to the gravity point. The gravity and anchor are both centered by default.

• Gravity syntax: l_gravity_[VALUE] or l_g_[VALUE]\
• Anchor syntax: l_anchor_[VALUE] or l_an_[VALUE]
• Gravity example: l_g_se\
• Anchor example: l_an_sw\

Gravity and anchor values

Offset X and Y values

The offset values represent the number or percentage of pixels the layer is pushed from the gravity position. Values between -1 and 1 (exclusive) are treated as percentages. Other whole numbers represent pixels. For east-aligned gravities, positive X offset moves left. For west-aligned gravities, positive X offset moves right (towards the center).

• Offset X syntax: l_offsetx_[VALUE] or l_ox_[VALUE]
• Offset y syntax: l_offsety_[VALUE] or l_oy_[VALUE]
• Rules to follow: Decimal values between -1 and 1 (exclusive) will offset the placement by percentage. Whole number values offset the placement by pixels.
• Offset X example: l_ox_10 (Moves the image 10 pixels to the left or right, depending on the gravity)
• Offset Y example: l_oy_0.3 (Moves the image 30% of the height, depending on the gravity)

Overflow behavior

If an overlay is larger than the base image, you can configure the overlay to overflow beyond the base image’s dimensions, or you can clip the excess overlay content to the size of the base image.

• Syntax: l_overflowbehavior_[VALUE] or l_overflow_[VALUE]
• Rules to follow: Enter expand or clip
• Example: l_overflow_clip

Overlay an image using an embed URL with existing transformations

As an alternative to adding an overlay image’s ID, you can use parentheses and overlay an image using its embed URL without the domain. You can generate embed URLs with the [get link APIs](ref:get-link-apis) and when sharing an asset in the UI. With this option, you can generate an embed URL with transformations and overlay the transformed image onto a base image.

Syntax: l_image_(<CustomEmbedPath>/t/<transformations>)

The /t/ separator splits the asset ID from the transformations applied to the layer, just like the base URL syntax.

Add transformations to the base image and the overlay in a single URL

Transformations can be applied to the base image both before and after layer overlays:

• Within the same URL segment: Transformations that come before the first l_image_ are applied to the base image. For example, the following transformation resizes the base image to 500x300, then adds the overlay:
  re_w_500,re_h_300,l_image_[ID\],l_g_SouthEast
• In a separate URL segment (after `/`): Transformations in subsequent segments are applied to the base image after the layer compositing from the previous segment. For example, the following transformation composes the overlay first. Then, the result is cropped to 550x800:
  l\_image_<accessKey>,l_g_nw,o_v_0.5,c_w_550,c_h_800,c_whu_Pixel,c_g_center

Both can be combined. For example, the following transformation resizes the base image to 1000 pixels wide, adds the overlay, and then crops the composite image to 550x800:
re_w_1000,l_image_<accessKey>,l_g_se,c_w_550,c_h_800,c_whu_Pixel,c_g_center

Multiple layers

You can add multiple layers to a single image at the same time. Layers are processed sequentially. Separate layer syntax with commas.

When applying multiple layers within the same transformation segment (separated by commas), the overlay positions (gravity, offset, and anchor) are all calculated relative to the original base image.

Example: /AssetLink/[base asset ID]/t/l_image_(embeddedUrl1),l_g_nw,l_image_(embeddedUrl2),l_g_se

However, if the layers are placed in separate transformation segments (separated by a slash instead of a comma), the transformations are applied sequentially from left to right. This means each subsequent layer is applied on top of the result of the previous transformation, not the original base image.

Example: /t/l_image_(embeddedUrl1),l_g_nw/l_image_(embeddedUrl2),l_g_se

Nested layers

You can overlay an image onto another image to nest layers. This is only supported when using embed URLs to identify overlays.

Example: /AssetLink/[base asset ID]/t/l_image_(embed_URL_1/t/l_image_(embed_URL_2),l_g_nw)

In this example, the first embed URL is overlaid on top of the base image, and the second embed URL is overlaid on top of the first embed URL.

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
}'