Conditional transformations

Cloudinary supports conditional transformations for images, where a transformation is only applied if a specified condition is met, for example, if an image's width is greater than 300 pixels, apply a certain transformation.

See also: Conditional transformations for video.

This page covers the condition syntax and the image characteristics and operators you can use. To learn how to apply a transformation when a condition is met, see Specifying transformations for a condition. For multiple AND/OR conditions and else branches, see Advanced conditional transformations.

Specifying conditions

To specify a condition to be met before applying a transformation, use the if parameter (also if in URLs). The if parameter accepts a string value detailing the condition to evaluate, and is specified in the URL in the following format:

if_<image characteristic>_<operator>_<image characteristic value>

Where:

• image characteristic: The image parameter representing the characteristic to evaluate, for example w (or width in SDKs).
• operator: The comparison operator for the comparison, for example lt for 'less than' (or < in SDKs).
• image characteristic value: A hard coded value to check against, a supported user-defined variable containing a value to check against, or a different image characteristic you want to compare to.

  For example, if you only want to apply a transformation to non-square images, you could check if the width characteristic of your image is not equal to its height characteristic: if_w_ne_h

See examples.

Supported image characteristics

Characteristic	Description
w	(also width in SDKs) The asset's current width.
iw	The asset's initial width.
h	(also height in SDKs) The asset's current height.
ih	The asset's initial height.
ar	(also aspect_ratio in SDKs) The aspect ratio of the asset. The compared value can be either decimal (e.g., 1.5) or a ratio (e.g., 3:4).
iar	The asset's initial aspect ratio.
ctx	A contextual metadata value assigned to an asset.
md	A structured metadata value assigned to an asset.
tags	The set of tags assigned to the asset.
tar (trimmed_aspect_ratio in SDKs)	The aspect ratio of the image IF it was trimmed (using the 'trim' effect) without actually trimming the image. The compared value can be either decimal (e.g., 1.5) or a ratio (e.g., 3:4).
cp	The current page in the image/document.
fc (face_count in SDKs)	The total number of detected faces in the image.
ccc (custom_coordinates_count in SDKs)	The number of custom coordinate sets defined for the image.
rc (regions_count in SDKs)	The number of named regions set on the image.
pc (page_count in SDKs)	The total number of pages in the image/document.
px	A layer or page's original x offset position relative to the whole composition (for example, in a PSD or TIFF file).
py	A layer or page's original y offset position relative to the whole composition (for example, in a PSD or TIFF file).
idn	The initial density (DPI) of the image.
ils	The likelihood that the image is an illustration (as opposed to a photo). Supported values: 0 (photo) to 1 (illustration)
rn (region_names in SDKs)	The names of regions set on the image. Use with the in or nin operators.
pgnames	The names of layers in a TIFF file. Use with the in or nin operators.

Supported operators

URL	SDK symbol	Description
eq	=	Equal to
ne	!=	Not equal to
lt	<	Less than
gt	>	Greater than
lte	<=	Less than or equal to
gte	>=	Greater than or equal to
in|nin	in|nin	Included in | Not included in Compares a set of strings against another set of strings. See Using the in and nin operators for examples.

When working with the Cloudinary SDKs, you can specify the condition using the SDK characteristic names and operator symbols, or you can specify it using the URL format. For example, both of the following are valid:

• { if: "w_gt_1000"},...
• { if: "width > 1000"},...

Using the in and nin operators

The in and nin operators compare two sets of strings. The : delimiter between strings denotes AND. String sets can include tags, contextual metadata or structured metadata values, for example:

• To determine if sale and in_stock are present in the tags of a particular asset, use:
  if_!sale:in_stock!_in_tags.
• To determine if the key named color exists in the contextual metadata of a particular asset, use:
  if_!color!_in_ctx.
• To determine if a structured metadata field with external ID, color-id, has been set for a particular asset, use:
  if_!color-id!_in_md.

• To determine if a list value with external ID, green-id, has been selected from a multiple-selection structured metadata field with external ID, colors-id, for a particular asset, use:
  if_!green-id!_in_md:!colors-id!.

• To determine if a region named hat has been set on an image, use:
  if_!hat!_in_rn.

For TIFF files:

• To determine if a TIFF file contains a layer called Shadow, use:
  if_!Shadow!_in_pgnames.

Supported features and limitations

The following sections describe which transformation parameters and flags are supported in conditional transformations, along with important limitations and behavior considerations to be aware of when building conditions.

Supported conditional image transformation parameters and flags

• All image transformation parameters can be assigned in conditions except:

  • You cannot assign transformation parameters for the format, fetch_format, default_image, color_space, or delay parameters.
  • The page (pg in URLs) parameter cannot be assigned for animated images
    (page can be used in conditions for PSD, PDF, or TIFF documents).
  • The angle parameter cannot be set to ignore.

• Only the following flags are supported inside conditional image transformations:
  layer_apply, region_relative, relative, progressive, cutter, png8, attachment, awebp, lossy

Notes and considerations

• For the w, h, cp and ar parameters, the values refer to the current image status in the transformation chain (i.e., if transformations have already been applied to the image), while iw, ih, fc and pc always refer to the original image.
• dpr is not supported as a conditional transformation with the cp and ar characteristics. Additionally, w and h are supported with dpr as long as they are still equal to iw or ih when the condition is evaluated. If dpr is specified in the transformation as a whole, and one of the conditional branches includes a resizing transformation, you need to specify a resize transformation in all the other branches too.
• The ar (aspect ratio) parameter should be compared using 'greater than' or 'less than' rather than with 'equals'. This is because the width and height values are given as integers and not floating point values, leading to an "almost exact" calculated aspect ratio.
• Contextual metadata values are always stored as strings, even if the value is numeric, therefore you cannot use the lt, gt, lte and gte operators to compare contextual metadata values numerically. You can, however, use these operators with numeric structured metadata values - see an example.
• You can test whether or not a variable has been defined using the parameters if_isdef_$<variable name> and if_isndef_$<variable name> (see Testing whether a variable has been defined).