Crop Images 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 image you want to crop.
2. Tap the crop icon in the editor toolbar.
3. Adjust the crop area by dragging the corners or edges.
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 image appears in your project, but the underlying original image and crop values are preserved even when you rotate or resize the cropped image.

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 .image. Otherwise setting the edit mode of the engine.editor to .crop has no effect.

Programmatic Cropping#

Programmatic cropping gives you complete control over image 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 an image 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 an image 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 image. The examples below always adjust the x and y values equally. This is not required, but adjusting them unequally can distort the image, which might be just what you want.

Reset Crop#

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

This is a block (called imageBlock in the example code) with dimensions of 400 × 400 filled with an image that has dimensions of 600 × 530. The image 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(imageBlock)

Crop Translation#

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

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

This image 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 image in the vertical direction. Negative values move the image up and positive values move the image 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(imageBlock)
let currentY = try engine.block.getCropTranslationY(imageBlock)

Crop Scale#

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

This image 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(imageBlock, scaleX:  1.50)
try engine.block.setCropScaleY(imageBlock, scaleY: 1.50)

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

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

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 image rotates around its center.

try engine.block.setCropRotation(block, 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 an image, 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 image has been scaled by 2.0 in the x and y directions. It’s translation has been adjusted by -0.5 in the x and y directions to keep the image centered.

try engine.block.setCropScaleRatio(imageBlock, 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(block, scaleX: 2.0)
try engine.block.setCropScaleY(block, scaleY: 2.0)
try engine.block.setCropTranslationX(block, translationX: -0.5)
try engine.block.setCropTranslationY(block, translationY: -0.5)

Chained Crops#

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

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

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

Flipping the Crop#

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

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

The image 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(imageBlock, minScaleRatio: 1.0)

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