Crop Video in iOS

Using the built-in crop UI#

CE.SDK provides a user-friendly cropping tool in its default UI. Users can interactively adjust crop areas, select preset aspect ratios, and apply changes with real-time feedback. This makes it easy to support social media presets or maintain brand consistency.

User interaction workflow#

1. Select the video you want to crop.
2. Tap the crop icon in the editor toolbar.
3. Adjust the crop area by dragging the corners or edges or using two-finger gestures.
4. Use the tools to modify the crop flip, rotation and angle or to reset the crop.
5. Close the Sheet to finalize the crop.

The cropped video appears in your project, but the underlying original video and crop values are preserved even when you rotate or resize the cropped video.

Enable and configure crop tool#

The default UI alows cropping. When you are creating your own UI or custom toolbars you can configure editing behavior. To ensure the crop tool is available in the UI, make sure it’s included in your dock configuration or quick actions.

try engine.editor.setSettingBool("doubleClickToCropEnabled", value: true)
try engine.editor.setSettingBool("controlGizmo/showCropHandles", value: true)
try engine.editor.setSettingBool("controlGizmo/showCropScaleHandles", value: true)

The cropping handles are only available when a selected block has a fill of type .video. Otherwise setting the edit mode of the engine.editor to .crop has no effect.

Programmatic Cropping#

Programmatic cropping gives you complete control over video block boundaries, dimensions, and integration with other transformations like rotation or flipping. This is useful for automation, predefined layouts, or server-synced workflows. When you initially create a fill to insert a video into a block, the engine centers the image in the block and crops any dimension that doesn’t match. For example: when a block with dimensions of 400.0 × 400.0 is filled with a video that is 600.0 × 500.0, there will be horizontal cropping.

When working with cropping using code, it’s important to remember that you are modifying the scale, translation, rotation, etc. of the underlying video. The examples below always adjust the x and y values equally. This is not required, but adjusting them unequally can distort the video, which might be just what you want.

Reset Crop#

When a video is initially placed into a block it will get crop scale and crop translation values. Resetting the crop will return the video to the original values.

This is a block (called videoBlock in the example code) with dimensions of 400 × 400 filled with a video that has dimensions of 720 × 1280. The video has slight scaling and translation applied so that it fills the block evenly. At any time, the code can execute the reset crop command to return it to this stage.

try engine.block.resetCrop(videoBlock)

Crop Translation#

The translation values adjust the placement of the origin point of a video. You can read and change the values. They are not pixel units or centimeters, they are scaled percentages. A video that has its origin point at the origin point of the crop block will have translation value of 0.0 for x and y.

try engine.block.setCropTranslationX(videoBlock, translationX: 0.250)

This video has had its translation in the x direction set to 0.25. That moved the image one quarter of its width to the right. Setting the value to -0.25 would change the offset of the origin to the left.

These are absolute values. Setting the x value to 0.25 and then setting it to -0.25 does not move the image to an offset of 0.0.

There is a setCropTranslationY(_ id: DesignBlockID, translationY: Float) function to adjust the translation of the video in the vertical direction. Negative values move the image up and positive values move the video down.

To read the current crop translation values you can use the convenience getters for the x and y values.

let currentX = try engine.block.getCropTranslationX(videoBlock)
let currentY = try engine.block.getCropTranslationY(videoBlock)

Crop scale#

The scale values adjust the height and width of the underlying video. Values larger than 1.0 will make the video larger while values less than 1.0 make the video smaller. Unless the video also has offsetting translation applied, the center of the image will move.

This video has been scaled by 1.5 in the x and y directions, but the origin point has not been translated. So, the center of the image has moved.

try engine.block.setCropScaleX(videoBlock, scaleX:  1.50)
try engine.block.setCropScaleY(videoBlock, scaleY: 1.50)

To read the current crop scale values, use the convenience getters for the x and y values.

let currentX = try engine.block.getCropScaleX(videoBlock)
let currentY = try engine.block.getCropScaleY(videoBlock)

Crop rotate#

The same as when rotating blocks, the crop rotation function uses radians. Positive values rotate clockwise and negative values rotate counter clockwise. The video rotates around its center.

try engine.block.setCropRotation(videoBlock, rotation: .pi / 4.0)

For working with radians, Swift has a constant defined for pi. It can be used as either Float.pi or Double.pi. Because the setCropRotation function takes a Float for the rotation value, you can use .pi and Swift will infer the correct type.

Crop to scale ratio#

To center crop a video, you can use the scale ratio. This will adjust the x and y scales of the image evenly, and adjust the translation to keep it centered.

This video has been scaled by 2.0 in the x and y directions. It’s translation has been adjusted automatically by -0.5 in the x and y directions to keep the image centered.

try engine.block.setCropScaleRatio(videoBlock, scaleRatio: 2.0)

Using the crop scale ratio function is the same as calling the translation and scale functions, but in one line.

try engine.block.setCropScaleX(videoBlock, scaleX: 2.0)
try engine.block.setCropScaleY(videoBlock, scaleY: 2.0)
try engine.block.setCropTranslationX(videoBlock, translationX: -0.5)
try engine.block.setCropTranslationY(videoBlock, translationY: -0.5)

Chained crops#

Crop operations can be chained together. The order of the chaining impacts the final video.

try engine.block.setCropScaleRatio(videoBlock, scaleRatio: 2.0)
try engine.block.setCropRotation(videoBlock, rotation: .pi / 3.0)

try engine.block.setCropRotation(videoBlock, rotation: .pi / 3.0)
try engine.block.setCropScaleRatio(videoBlock, scaleRatio: 2.0)

Flipping the crop#

There are two functions for crop flipping the video. One for horizontal and one for vertical. They each flip the video along its center.

try engine.block.flipCropVertical(videoBlock)
try engine.block.flipCropHorizontal(videoBlock)

The video will be crop flipped every time the function gets called. So calling the function an even number of times will return the image to its original orientation.

Filling the frame#

When the various crop operations cause the background of the crop block to be displayed, such as in the Crop Translation example above, the function

try engine.block.adjustCropToFillFrame(videoBlock, minScaleRatio: 1.0)

will adjust the translation values and the scale values of the video so that the entire crop block is filled. This is not the same as resetting the crop.