Programmatic Editing - Android

import android.net.Uri
import ly.img.engine.ContentFillMode
import ly.img.engine.DesignBlockType
import ly.img.engine.EffectType
import ly.img.engine.Engine
import ly.img.engine.FillType
import ly.img.engine.MimeType

suspend fun editImageProgrammatically(engine: Engine): ProgrammaticImageEditResult {
    val imageUri = Uri.parse("https://img.ly/static/ubq_samples/sample_1.jpg")
    engine.scene.createFromImage(imageUri)

    val page = engine.block.findByType(DesignBlockType.Page).first()
    val imageFill = engine.block.getFill(page)

    require(engine.block.getType(imageFill) == FillType.Image.key) {
        "Expected the imported page to use an image fill."
    }

    engine.block.setWidth(block = page, value = 900F)
    engine.block.setHeight(block = page, value = 600F)
    engine.block.setContentFillMode(block = page, mode = ContentFillMode.COVER)

    val adjustment = engine.block.createEffect(type = EffectType.Adjustments)
    engine.block.appendEffect(block = page, effectBlock = adjustment)
    engine.block.setFloat(adjustment, property = "effect/adjustments/brightness", value = 0.08F)
    engine.block.setFloat(adjustment, property = "effect/adjustments/contrast", value = 0.18F)

    val editedPng = engine.block.export(block = page, mimeType = MimeType.PNG)

    check(editedPng.hasRemaining()) { "PNG export is empty." }

    return ProgrammaticImageEditResult(
        width = engine.block.getWidth(page),
        height = engine.block.getHeight(page),
        fillMode = engine.block.getContentFillMode(page),
        brightness = engine.block.getFloat(adjustment, property = "effect/adjustments/brightness"),
        contrast = engine.block.getFloat(adjustment, property = "effect/adjustments/contrast"),
        imageFillType = engine.block.getType(imageFill),
        exportedPng = editedPng.asReadOnlyBuffer(),
    )
}

import ly.img.engine.ContentFillMode
import java.nio.ByteBuffer

data class ProgrammaticImageEditResult(
    val width: Float,
    val height: Float,
    val fillMode: ContentFillMode,
    val brightness: Float,
    val contrast: Float,
    val imageFillType: String,
    val exportedPng: ByteBuffer,
)

Edit images with CE.SDK Engine APIs when your app needs automation, template-driven output, or custom controls outside the editor UI.

Programmatic image editing result with resized, cropped, and adjusted image content

6 mins

estimated time

GitHub

Programmatic image editing works directly on the Engine scene graph. Use this approach when app logic should load an image, apply a known edit recipe, and export the result without asking the user to perform every operation in the CE.SDK editor UI. For an interactive product surface, start with the Photo Editor Starter Kit instead.

This guide loads an image scene, locates the image-backed page, applies a small set of block edits, adds a lightweight adjustment effect, and exports a PNG. Dedicated Android guides cover deeper transform, crop, watermark, and export workflows.

Load an Image Scene#

Start by creating a scene from an image URI. CE.SDK imports the image into a scene with a page that can be edited through the Block API.

val imageUri = Uri.parse("https://img.ly/static/ubq_samples/sample_1.jpg")
engine.scene.createFromImage(imageUri)

createFromImage() accepts Android Uri values, including app storage, resource, file, and remote URLs that your app is allowed to load.

Find the Image Block#

After loading, find the page and read its fill. In this workflow, the imported page is the image-bearing block that later edits and export calls target.

val page = engine.block.findByType(DesignBlockType.Page).first()
val imageFill = engine.block.getFill(page)

require(engine.block.getType(imageFill) == FillType.Image.key) {
    "Expected the imported page to use an image fill."
}

The type check keeps the sample explicit: the page fill must be an image fill before the code applies image-editing operations to the page.

Apply Basic Image Edits#

Set the output frame and choose how the image fits that frame. These are representative block-level edits; use the focused transform and crop guides when your app needs full transform controls.

engine.block.setWidth(block = page, value = 900F)
engine.block.setHeight(block = page, value = 600F)
engine.block.setContentFillMode(block = page, mode = ContentFillMode.COVER)

ContentFillMode.COVER scales the image to cover the page frame and may crop the edges. Use ContentFillMode.CONTAIN when the whole image must remain visible inside the frame.

Add an Adjustment Effect#

Effects let you combine visual edits with the same scene workflow. This sample adds an adjustments effect and writes two image adjustment properties.

val adjustment = engine.block.createEffect(type = EffectType.Adjustments)
engine.block.appendEffect(block = page, effectBlock = adjustment)
engine.block.setFloat(adjustment, property = "effect/adjustments/brightness", value = 0.08F)
engine.block.setFloat(adjustment, property = "effect/adjustments/contrast", value = 0.18F)

Keep guide-level adjustment recipes small. The Adjust Colors guide covers adjustment properties, effect ordering, and reset behavior in more detail.

Export the Edited Image#

Export the edited page as PNG once all programmatic edits are applied. The returned ByteBuffer contains the image bytes your app can save, upload, or decode.

val editedPng = engine.block.export(block = page, mimeType = MimeType.PNG)

check(editedPng.hasRemaining()) { "PNG export is empty." }

Use the broader Export guide for format selection, target dimensions, compression options, and export constraints.

API Reference#

Android API	Purpose
`engine.scene.createFromImage(imageUri=_)`	Create a scene from an image URI.
`engine.block.findByType(type=_)`	Locate pages or other typed blocks in the current scene.
`engine.block.getFill(block=_)`	Read the fill assigned to the image-bearing page.
`engine.block.getType(block=_)`	Check that the loaded fill is an image fill.
`engine.block.setWidth(block=_, value=_)`	Set the page width in scene units.
`engine.block.setHeight(block=_, value=_)`	Set the page height in scene units.
`engine.block.setContentFillMode(block=_, mode=_)`	Control how the image fits inside the page frame.
`engine.block.createEffect(type=_)`	Create an effect block such as `EffectType.Adjustments`.
`engine.block.appendEffect(block=_, effectBlock=_)`	Add an effect to a block’s effect stack.
`engine.block.setFloat(block=_, property="effect/adjustments/brightness", value=_)`	Set adjustment brightness.
`engine.block.setFloat(block=_, property="effect/adjustments/contrast", value=_)`	Set adjustment contrast.
`engine.block.export(block=_, mimeType=_)`	Render the edited page to image bytes.

Next Steps#

Transform Images - Crop, resize, rotate, scale, or flip images using CE.SDK’s built-in transformation tools.
Crop Images - Cut out specific areas of an image to focus on key content or change aspect ratio.
Add Watermark - Add text and image watermarks to protect images, indicate ownership, or add branding using CE.SDK in Android.
Export - Explore export options, supported formats, and configuration features for sharing or rendering output.