class Transformation extends CommonTransformation

Defines how to manipulate and transform images.

Learn more: Image transformations

Methods

resize(BaseResizeAction $resize)

Resize the asset using provided resize action

scale(int|float|string|null $width = null, int|float|null $height = null, int|float|array $aspectRatio = null)

Change the size of the image exactly to the given width and height without necessarily retaining the original aspect ratio: all original image parts are visible but might be stretched or shrunk.

crop(int|float|string|null $width = null, int|float|null $height = null, Gravity $gravity = null, int|float|X $x = null, int|float|Y $y = null)

Extracts a region of the given width and height out of the original image.

fill(int|float|string|null $width = null, int|float|null $height = null, Gravity $gravity = null)

Creates an image with the exact given width and height without distorting the image.

genericResize(string $name, int|float|string|null $width = null, int|float|null $height = null)

Custom resize builder.

delivery(mixed $delivery)

Applies delivery action.

format(Format|string $format)

Forces format conversion to the given format.

quality(int|string|Quality $quality)

Controls compression quality. 1 is the lowest quality and 100 is the highest.

dpr(float|string $dpr)

Deliver the image in the specified device pixel ratio.

attachment(string $filename = null)

Delivers the image as an attachment.

forceIcc()

Adds ICC color space metadata to the image, even when the original image doesn't contain any ICC data.

forceStrip()

Instructs Cloudinary to clear all image meta-data (IPTC, Exif and XMP) while applying an incoming transformation.

getInfo()

Returns metadata of the input asset and of the transformed output asset in JSON instead of the transformed image.

immutableCache()

Sets the cache-control to immutable for the asset.

keepAttribution()

Keeps the copyright related fields when stripping meta-data.

keepIptc()

Keeps all meta-data.

stripProfile()

Instructs Cloudinary to clear all ICC color profile data included with the image.

customFunction(CustomFunction $customFunction)

Inject a custom function into the image transformation pipeline.

effect(EffectQualifier|EffectAction $effect)

Applies a filter or an effect on an asset.

adjust(EffectQualifier|EffectAction|AdjustmentInterface $adjustment)

Applies adjustment effect on an asset.

namedTransformation(string|NamedTransformation $transformationName)

Applies a pre-defined named transformation of the given name.

addGenericQualifier(string $shortName, array|mixed ...$value)

Adds a generic qualifier as a separate action.

addActionFromQualifiers(array $qualifiers)

Adds action defined as an array of qualifiers.

addFlag(FlagQualifier|string $flag)

Adds a flag as a separate action.

addVariable(string|Variable $name, mixed $value = null)

Defines an new user variable.

rotate(string|int $angle)

Rotates the asset by the given angle.

conditional(Conditional $conditionalTransformation)

Specifies a conditional transformation whose condition should be met before applying a transformation.

sanitize()

Instruct Cloudinary to run a sanitizer on the image (relevant only for the SVG format).

delay(Delay|int $delay)

Sets the delay between frames of an animated image in milliseconds.

defaultImage(string $defaultImage)

Default images can be used in the case that a requested image does not exist.

density(int|string $density)

Controls the density to use when delivering an image or when converting a vector file such as a PDF or EPS document to a web image delivery format.

prefix(string $prefix)

Prevents style class names collisions for sprite generation.

extract(PageQualifier|string|int ...$pages)

Extracts selected pages/frames from the asset.

psdTools(PageQualifier|string|int ...$pages)

Extracts selected layers/embedded objects from the PSD file.

overlay(BaseSource|string $videoLayer, BasePosition|null $position = null, Timeline|null $timeline = null)

Adds another video, text, image as an overlay over the container video.

underlay(string $layer, Position|AbsolutePosition $position = null, string $blendMode = null)

Adds an underlay under the base image.

reshape(ReshapeQualifier|EffectAction|EffectQualifier|mixed $reshape)

Changes the shape of the image.

roundCorners(int|string $radius)

Rounds the corners of a video.

border(Border $border)

Adds a border around the image.

backgroundColor(Background|ColorValue|string $color)

Sets the color of the background.

background(Background|string $background)

Sets the image background.

colorSpace(ColorSpace|string $colorSpace)

Controls the color space used for the delivered image.

animated(AnimatedEdit $animated)

Applies animated image transformation action.

noStream()

Don't stream a video that is currently being generated on the fly. Wait until the video is fully generated.

streamingAttachment(string $filename = null)

Causes the video download to begin immediately, streaming it as a fragmented video file.

hlsv3()

Deliver an HLS adaptive bitrate streaming file as HLS v3 instead of the default version (HLS v4).

keepDar()

Keep the Display Aspect Ratio metadata of the uploaded video.

mono()

Convert the audio channel to mono.

truncateTS()

Truncate (trim) a video file based on the start time defined in the metadata.

waveform()

Create a waveform image (in the format specified by the file extension) from the audio or video file.

trim(Timeline $range)

Trims a video (and discards the rest).

concatenate(VideoSource|string $videoSource)

Concatenates another video or image.

cutter(VideoSource|string $videoLayer, BasePosition|null $position = null, Timeline|null $timeline = null)

Applies the video as a cutter for the main video.

addSubtitles(string $subtitlesId)

Adds subtitles to the video.

transcode(AudioCodec|VideoCodec|AudioFrequency|mixed $transcode)

Transcodes the video (or audio) to another format / adjusts encoding properties.

fps(float|int|string $min, float|int|string|null $max = null)

Controls the range of acceptable FPS (Frames Per Second) to ensure that video (even when optimized) is delivered with an expected fps level (helps with sync to audio).

keyframeInterval(float $interval)

Explicitly sets the keyframe interval of the delivered video.

bitRate(int|string $bitRate, string $type = null)

Controls the video bitrate.

streamingProfile(string $streamingProfile)

Sets the streaming profile to apply to an HLS or MPEG-DASH adaptive bitrate streaming video.

videoSampling(int|string $value)

Sets the total number of frames to sample from the original video.

videoEdit(mixed $videoEdit)

Applies the specified video edit action.

Details

TransformationResizeTrait resize(BaseResizeAction $resize)

Resize the asset using provided resize action

Parameters

Name Type Description
$resize BaseResizeAction The resize action

Return Value

TransformationResizeTrait

TransformationResizeTrait scale(int|float|string|null $width = null, int|float|null $height = null, int|float|array $aspectRatio = null)

Change the size of the image exactly to the given width and height without necessarily retaining the original aspect ratio: all original image parts are visible but might be stretched or shrunk.

Parameters

Name Type Description
$width int|float|string|null The required width of a transformed asset.
$height int|float|null The required height of a transformed asset.
$aspectRatio int|float|array Resizes the asset to a new aspect ratio.

Return Value

TransformationResizeTrait

TransformationResizeTrait crop(int|float|string|null $width = null, int|float|null $height = null, Gravity $gravity = null, int|float|X $x = null, int|float|Y $y = null)

Extracts a region of the given width and height out of the original image.

Parameters

Name Type Description
$width int|float|string|null The required width of a transformed asset.
$height int|float|null The required height of a transformed asset.
$gravity Gravity Which part of the original image to include.
$x int|float|X Horizontal position for custom-coordinates based cropping
$y int|float|Y Vertical position for custom-coordinates based cropping

Return Value

TransformationResizeTrait

TransformationResizeTrait fill(int|float|string|null $width = null, int|float|null $height = null, Gravity $gravity = null)

Creates an image with the exact given width and height without distorting the image.

This option first scales up or down as much as needed to at least fill both of the given dimensions. If the requested aspect ratio is different than the original, cropping will occur on the dimension that exceeds the requested size after scaling.

Parameters

Name Type Description
$width int|float|string|null The required width of a transformed asset.
$height int|float|null The required height of a transformed asset.
$gravity Gravity Which part of the original image to include when the resulting image is smaller than the original or the proportions do not match.

Return Value

TransformationResizeTrait

TransformationResizeTrait genericResize(string $name, int|float|string|null $width = null, int|float|null $height = null)

Custom resize builder.

Parameters

Name Type Description
$name string Provide future (not supported in the current version) resize name
$width int|float|string|null The required width of a transformed asset.
$height int|float|null The required height of a transformed asset.

Return Value

TransformationResizeTrait

TransformationDeliveryTrait delivery(mixed $delivery)

Applies delivery action.

Parameters

Name Type Description
$delivery mixed The delivery action to apply.

Return Value

TransformationDeliveryTrait

TransformationDeliveryTrait format(Format|string $format)

Forces format conversion to the given format.

(Formerly known as fetch format)

Parameters

Name Type Description
$format Format|string

Return Value

TransformationDeliveryTrait

TransformationDeliveryTrait quality(int|string|Quality $quality)

Controls compression quality. 1 is the lowest quality and 100 is the highest.

Reducing the quality is a trade-off between visual quality and file size.

Parameters

Name Type Description
$quality int|string|Quality

Return Value

TransformationDeliveryTrait

TransformationDeliveryTrait dpr(float|string $dpr)

Deliver the image in the specified device pixel ratio.

Parameters

Name Type Description
$dpr float|string Any positive float value.

Return Value

TransformationDeliveryTrait

CommonTransformationFlagTrait attachment(string $filename = null)

Delivers the image as an attachment.

Parameters

Name Type Description
$filename string The attachment's filename

Return Value

CommonTransformationFlagTrait

See also

Flag::attachment

CommonTransformationFlagTrait forceIcc()

Adds ICC color space metadata to the image, even when the original image doesn't contain any ICC data.

Return Value

CommonTransformationFlagTrait

See also

Flag::forceIcc

CommonTransformationFlagTrait forceStrip()

Instructs Cloudinary to clear all image meta-data (IPTC, Exif and XMP) while applying an incoming transformation.

Return Value

CommonTransformationFlagTrait

See also

Flag::forceStrip

CommonTransformationFlagTrait getInfo()

Returns metadata of the input asset and of the transformed output asset in JSON instead of the transformed image.

Return Value

CommonTransformationFlagTrait

See also

Flag::getInfo

CommonTransformationFlagTrait immutableCache()

Sets the cache-control to immutable for the asset.

Return Value

CommonTransformationFlagTrait

See also

Flag::immutableCache

CommonTransformationFlagTrait keepAttribution()

Keeps the copyright related fields when stripping meta-data.

Return Value

CommonTransformationFlagTrait

See also

Flag::keepAttribution

CommonTransformationFlagTrait keepIptc()

Keeps all meta-data.

Return Value

CommonTransformationFlagTrait

See also

Flag::keepIptc

CommonTransformationFlagTrait stripProfile()

Instructs Cloudinary to clear all ICC color profile data included with the image.

Return Value

CommonTransformationFlagTrait

See also

Flag::stripProfile

TransformationCustomFunctionTrait customFunction(CustomFunction $customFunction)

Inject a custom function into the image transformation pipeline.

Parameters

Name Type Description
$customFunction CustomFunction The custom function source

Return Value

TransformationCustomFunctionTrait

CommonTransformationTrait effect(EffectQualifier|EffectAction $effect)

Applies a filter or an effect on an asset.

Parameters

Name Type Description
$effect EffectQualifier|EffectAction

Return Value

CommonTransformationTrait

CommonTransformationTrait adjust(EffectQualifier|EffectAction|AdjustmentInterface $adjustment)

Applies adjustment effect on an asset.

Parameters

Name Type Description
$adjustment EffectQualifier|EffectAction|AdjustmentInterface

Return Value

CommonTransformationTrait

CommonTransformationTrait namedTransformation(string|NamedTransformation $transformationName)

Applies a pre-defined named transformation of the given name.

Parameters

Name Type Description
$transformationName string|NamedTransformation

Return Value

CommonTransformationTrait

CommonTransformationTrait addGenericQualifier(string $shortName, array|mixed ...$value)

Adds a generic qualifier as a separate action.

Parameters

Name Type Description
$shortName string The generic qualifier name.
...$value array|mixed The generic qualifier value.

Return Value

CommonTransformationTrait

CommonTransformationTrait addActionFromQualifiers(array $qualifiers)

Adds action defined as an array of qualifiers.

Parameters

Name Type Description
$qualifiers array An associative array of qualifiers

Return Value

CommonTransformationTrait

See also

QualifiersAction

CommonTransformationTrait addFlag(FlagQualifier|string $flag)

Adds a flag as a separate action.

Parameters

Name Type Description
$flag FlagQualifier|string The flag to add.

Return Value

CommonTransformationTrait

CommonTransformationTrait addVariable(string|Variable $name, mixed $value = null)

Defines an new user variable.

Parameters

Name Type Description
$name string|Variable The variable name or the Variable instance.
$value mixed The variable value.

Return Value

CommonTransformationTrait

CommonTransformationTrait rotate(string|int $angle)

Rotates the asset by the given angle.

Parameters

Name Type Description
$angle string|int The rotation angle.

Return Value

CommonTransformationTrait

CommonTransformationTrait conditional(Conditional $conditionalTransformation)

Specifies a conditional transformation whose condition should be met before applying a transformation.

Parameters

Name Type Description
$conditionalTransformation Conditional The conditional transformation.

Return Value

CommonTransformationTrait

See also

https://cloudinary.com/documentation/conditional_transformations

ImageTransformationFlagTrait sanitize()

Instruct Cloudinary to run a sanitizer on the image (relevant only for the SVG format).

ImageQualifierTransformationTrait delay(Delay|int $delay)

Sets the delay between frames of an animated image in milliseconds.

Parameters

Name Type Description
$delay Delay|int

Return Value

ImageQualifierTransformationTrait

$this defaultImage(string $defaultImage)

Default images can be used in the case that a requested image does not exist.

Parameters

Name Type Description
$defaultImage string Default image public ID

Return Value

$this

Density density(int|string $density)

Controls the density to use when delivering an image or when converting a vector file such as a PDF or EPS document to a web image delivery format.

Parameters

Name Type Description
$density int|string The density in dpi.

Return Value

Density

Prefix prefix(string $prefix)

Prevents style class names collisions for sprite generation.

Parameters

Name Type Description
$prefix string The style class name prefix.

Return Value

Prefix

LayeredImageTransformationTrait extract(PageQualifier|string|int ...$pages)

Extracts selected pages/frames from the asset.

Parameters

Name Type Description
...$pages PageQualifier|string|int

Return Value

LayeredImageTransformationTrait

See also

https://cloudinary.com/documentation/paged_and_layered_media#deliver_a_pdf_or_selected_pages_of_a_pdf

LayeredImageTransformationTrait psdTools(PageQualifier|string|int ...$pages)

Extracts selected layers/embedded objects from the PSD file.

Parameters

Name Type Description
...$pages PageQualifier|string|int

Return Value

LayeredImageTransformationTrait

See also

https://cloudinary.com/documentation/paged_and_layered_media#deliver_a_pdf_or_selected_pages_of_a_pdf

VideoSpecificTransformationTrait overlay(BaseSource|string $videoLayer, BasePosition|null $position = null, Timeline|null $timeline = null)

Adds another video, text, image as an overlay over the container video.

Parameters

Name Type Description
$videoLayer BaseSource|string The overlay.
$position BasePosition|null The position of the overlay.
$timeline Timeline|null The timeline position of the overlay.

Return Value

VideoSpecificTransformationTrait

See also

https://cloudinary.com/documentation/video_manipulation_and_delivery#adding_video_overlays

ImageSpecificTransformationTrait underlay(string $layer, Position|AbsolutePosition $position = null, string $blendMode = null)

Adds an underlay under the base image.

Parameters

Name Type Description
$layer string The public ID of the image to underlay.
$position Position|AbsolutePosition The position of the underlay with respect to the base image.
$blendMode string The blend mode. Use the constants defined in the BlendMode class.

Return Value

ImageSpecificTransformationTrait

See also

OverlayOverlay
BlendMode

ImageSpecificTransformationTrait reshape(ReshapeQualifier|EffectAction|EffectQualifier|mixed $reshape)

Changes the shape of the image.

Parameters

Name Type Description
$reshape ReshapeQualifier|EffectAction|EffectQualifier|mixed The reshape to apply.

Return Value

ImageSpecificTransformationTrait

VideoSpecificTransformationTrait roundCorners(int|string $radius)

Rounds the corners of a video.

Parameters

Name Type Description
$radius int|string The radius of the corners in pixels.

Return Value

VideoSpecificTransformationTrait

See also

https://cloudinary.com/documentation/video_manipulation_and_delivery#rounding_corners_and_creating_circular_videos

ImageSpecificTransformationTrait border(Border $border)

Adds a border around the image.

Parameters

Name Type Description
$border Border A Border object in which you set the width, style and color of the border. See the Border class.

Return Value

ImageSpecificTransformationTrait

See also

Border

ImageSpecificTransformationTrait backgroundColor(Background|ColorValue|string $color)

Sets the color of the background.

Parameters

Name Type Description
$color Background|ColorValue|string The color of the background to set.

Return Value

ImageSpecificTransformationTrait

See also

Background

ImageSpecificTransformationTrait background(Background|string $background)

Sets the image background.

Parameters

Name Type Description
$background Background|string The background to set.

Return Value

ImageSpecificTransformationTrait

See also

Background

ImageSpecificTransformationTrait colorSpace(ColorSpace|string $colorSpace)

Controls the color space used for the delivered image.

Parameters

Name Type Description
$colorSpace ColorSpace|string Use the constants defined in the ColorSpace class.

Return Value

ImageSpecificTransformationTrait

See also

ColorSpace

ImageSpecificTransformationTrait animated(AnimatedEdit $animated)

Applies animated image transformation action.

Parameters

Name Type Description
$animated AnimatedEdit Animated image action.

Return Value

ImageSpecificTransformationTrait

VideoTransformationFlagTrait noStream()

Don't stream a video that is currently being generated on the fly. Wait until the video is fully generated.

VideoTransformationFlagTrait streamingAttachment(string $filename = null)

Causes the video download to begin immediately, streaming it as a fragmented video file.

Parameters

Name Type Description
$filename string The attachment's filename

Return Value

VideoTransformationFlagTrait

See also

Flag::streamingAttachment

VideoTransformationFlagTrait hlsv3()

Deliver an HLS adaptive bitrate streaming file as HLS v3 instead of the default version (HLS v4).

Return Value

VideoTransformationFlagTrait

See also

Flag::hlsv3

VideoTransformationFlagTrait keepDar()

Keep the Display Aspect Ratio metadata of the uploaded video.

VideoTransformationFlagTrait mono()

Convert the audio channel to mono.

VideoTransformationFlagTrait truncateTS()

Truncate (trim) a video file based on the start time defined in the metadata.

VideoTransformationFlagTrait waveform()

Create a waveform image (in the format specified by the file extension) from the audio or video file.

VideoSpecificTransformationTrait trim(Timeline $range)

Trims a video (and discards the rest).

Parameters

Name Type Description
$range Timeline Specify the range of the video to leave.

Return Value

VideoSpecificTransformationTrait

See also

https://cloudinary.com/documentation/video_manipulation_and_delivery#trimming_videos

VideoSpecificTransformationTrait concatenate(VideoSource|string $videoSource)

Concatenates another video or image.

Parameters

Name Type Description
$videoSource VideoSource|string The source of the video to concatenate.

Return Value

VideoSpecificTransformationTrait

See also

https://cloudinary.com/documentation/video_manipulation_and_delivery#concatenating_videos

VideoSpecificTransformationTrait cutter(VideoSource|string $videoLayer, BasePosition|null $position = null, Timeline|null $timeline = null)

Applies the video as a cutter for the main video.

Parameters

Name Type Description
$videoLayer VideoSource|string The cutter video layer.
$position BasePosition|null The position of the cutter.
$timeline Timeline|null The timeline position of the cutter.

Return Value

VideoSpecificTransformationTrait

VideoSpecificTransformationTrait addSubtitles(string $subtitlesId)

Adds subtitles to the video.

Parameters

Name Type Description
$subtitlesId string The subtitles file public ID.

Return Value

VideoSpecificTransformationTrait

VideoSpecificTransformationTrait transcode(AudioCodec|VideoCodec|AudioFrequency|mixed $transcode)

Transcodes the video (or audio) to another format / adjusts encoding properties.

Parameters

Name Type Description
$transcode AudioCodec|VideoCodec|AudioFrequency|mixed The new format or encoding property.

Return Value

VideoSpecificTransformationTrait

VideoSpecificTransformationTrait fps(float|int|string $min, float|int|string|null $max = null)

Controls the range of acceptable FPS (Frames Per Second) to ensure that video (even when optimized) is delivered with an expected fps level (helps with sync to audio).

Parameters

Name Type Description
$min float|int|string The minimum frame rate.
$max float|int|string|null The maximum frame rate.

Return Value

VideoSpecificTransformationTrait

VideoSpecificTransformationTrait keyframeInterval(float $interval)

Explicitly sets the keyframe interval of the delivered video.

Parameters

Name Type Description
$interval float Positive float number in seconds.

Return Value

VideoSpecificTransformationTrait

VideoSpecificTransformationTrait bitRate(int|string $bitRate, string $type = null)

Controls the video bitrate.

Parameters

Name Type Description
$bitRate int|string The number of bits used to represent the video data per second. By default the video uses a variable bitrate (VBR), with this value indicating the maximum bitrate. Can be an integer e.g. 120000, or a string supporting "k" and "m" (kilobits and megabits respectively) e.g. 250k or 2m.
$type string The type of bitrate. If "constant" is specified, the video plays with a constant bitrate (CBR). Use the constant defined in the BitRate class.

Return Value

VideoSpecificTransformationTrait

VideoSpecificTransformationTrait streamingProfile(string $streamingProfile)

Sets the streaming profile to apply to an HLS or MPEG-DASH adaptive bitrate streaming video.

The value can be one of the pre-defined streaming profiles or a custom-defined one. You can use the streaming profiles methods of StreamingProfilesTrait to get a list of the available streaming profiles or to create new custom profiles.

Parameters

Name Type Description
$streamingProfile string The streaming profile.

Return Value

VideoSpecificTransformationTrait

See also

https://cloudinary.com/documentation/video_manipulation_and_delivery#predefined_streaming_profiles
StreamingProfilesTrait

VideoSpecificTransformationTrait videoSampling(int|string $value)

Sets the total number of frames to sample from the original video.

Relevant when converting videos to animated GIF or WebP format. If not specified, the resulting GIF or WebP samples the whole video (up to 400 frames, at up to 10 frames per second). By default the duration of the animated image is the same as the duration of the video, no matter how many frames are sampled from the original video (use the delay qualifier to adjust the amount of time between frames).

Parameters

Name Type Description
$value int|string Integer - The total number of frames to sample from the original video. The frames are spread out over the length of the video, e.g. 20 takes one frame every 5%. String - The number of seconds between each frame to sample from the original video. e.g. 2.3s takes one frame every 2.3 seconds.

Return Value

VideoSpecificTransformationTrait

VideoSpecificTransformationTrait videoEdit(mixed $videoEdit)

Applies the specified video edit action.

Parameters

Name Type Description
$videoEdit mixed The video edit action.

Return Value

VideoSpecificTransformationTrait