Scale Images

Requirements#

• Node.js 18 or newer
• CE.SDK server package: npm install @cesdk/node

What You’ll Learn#

• Scale an image block uniformly or along a single axis.
• Scale blocks together while keeping their relative layout.
• Lock scaling and transformations in templates.

When to Use#

Server-side scaling helps when you need to:

• Emphasize or de-emphasize elements.
• Fit images to available space without cropping.
• Enable dynamic layouts or automated resizing.
• Create zoom effects programmatically.

How Scaling Works#

Scaling uses the scale(block, scale:number, anchorX, anchorY) function, with the following parameters:

A value of 2.0, for example, makes the block twice as large.

import 'dotenv/config';
import fs from 'fs/promises';
import path from 'path';
import CreativeEngine from '@cesdk/node';

async function run() {
  const engine = await CreativeEngine.init({
    license: process.env.LICENSE_KEY,
    baseURL: process.env.CESDK_BASE_URL
  });

  try {
    const scene = engine.scene.create();
    const page = engine.block.create('page');
    engine.block.appendChild(scene, page);

    const imageUrl = 'https://img.ly/static/ubq_samples/sample_1.jpg';
    const graphic = engine.block.create('graphic');
    engine.block.setShape(graphic, engine.block.createShape('rect'));

    const imageFill = engine.block.createFill('image');
    engine.block.setFill(graphic, imageFill);
    await engine.block.addImageFileURIToSourceSet(
      imageFill,
      'fill/image/sourceSet',
      imageUrl
    );
    engine.block.setString(imageFill, 'fill/image/imageFileURI', imageUrl);
    engine.block.appendChild(page, graphic);

    const [source] = engine.block.getSourceSet(
      imageFill,
      'fill/image/sourceSet'
    );
    if (!source) {
      throw new Error(`Image metadata not available for ${imageUrl}`);
    }

    engine.block.setSize(graphic, source.width, source.height, {
      sizeMode: 'Absolute'
    });
    engine.block.resetCrop(graphic);
    engine.block.scale(graphic, 2, 0.5, 0.5);

    const blob = await engine.block.export(graphic, { mimeType: 'image/png' });
    const outputPath = path.resolve('./scaled-image.png');
    await fs.mkdir(path.dirname(outputPath), { recursive: true });
    await fs.writeFile(outputPath, Buffer.from(await blob.arrayBuffer()));
    console.log(`Exported scaled image to ${outputPath}`);
  } finally {
    engine.dispose();
  }
}

run().catch((error) => {
  console.error('Scaling demo failed:', error);
});

Scale an Image Uniformly#

Scaling uniformly keeps the image’s aspect ratio intact while making it larger or smaller. This allows for applying zoom levels without stretching or squashing the artwork. For example:

engine.block.scale(blockId, 1.5);

The preceding code:

• Scales the image to 150% of its original size.
• Doesn’t change the origin anchor point.

As a result, the image expands down and to the right.

Anchor Point#

By default, the anchor point for the image when scaling is the top left. The scale function has two optional parameters:

• x to move the anchor point along the width.
• y to move the anchor point along the height.

They can have values between 0.0 and 1.0. For example:

engine.block.scale(blockId, 1.5, 0.5, 0.5)

This function:

1. Scales the image to 150% of its original size.
2. The origin anchor point is 0.5, 0.5, so the image expands from the center.

Scale Non-Uniformly#

To stretch or compress only one axis, thus distorting an image, use the width or height function. For example, to scale an image horizontally, you can use:

engine.block.setWidthMode(graphic, 'Absolute');
const width = engine.block.getWidth(graphic) * 1.5;
engine.block.setWidth(graphic, width, true );

The preceding code:

1. Sets the width position as 'Absolute' so width changes use a fixed pixel value instead of a relative layout mode.
2. Reads the current width and multiplies it by 1.5 to compute a new width that’s 150% of the original.
3. Writes the new width back to the block while keeping the height in proportion when available.

As a result, it stretches the element horizontally by the calculated factor:

Use this to:

• Create panoramic crops.
• Compensate for aspect ratios during automation.

Below are two examples of scaling the original image in the x direction only:

1. Double the width:

const width = engine.block.getWidth(graphic) * 2;

2. Scale horizontally by 2.5:

const width = engine.block.getWidth(graphic) * 2.5;

Scale elements together#

Group blocks to scale them proportionally:

const groupId = engine.block.group([imageId, textId]);
engine.block.scale(groupId, 1.75, 0.75, 0.5)

The preceding code scales the entire group to 75%.

Lock Scaling in Templates#

Lock scaling when you must preserve a template’s layout. This is useful for:

• Brand assets
• Campaign creatives
• Collaboration workflows
• Fixed dimensions swapping editors

When working with templates, prevent users from scaling blocks by turning off the layer/resize scope:

// Prevent scaling/resizing of a block
engine.block.setScopeEnabled(imageId, 'layer/resize', false);

Lock All Transformations#

Available block transformations are the following:

• Move
• Resize
• Rotate

To lock all transformations, use the following function:

// Lock all transforms
engine.block.setTransformLocked(imageId, true);

To check if scaling is currently allowed, log the output if isScopeEnabled:

// Check if resize is enabled
const canResize = engine.block.isScopeEnabled(imageId, 'layer/resize');
console.log('layer/resize scope enabled?', canResize);

Troubleshooting#

Next Steps#

Continue exploring CE.SDK automation features:

• Combine scaling with rotation or cropping> for richer automation flows.
• Export to different formats once the scale looks right.
• Create a template .

API references in this guide#