Search
Loading...
Skip to content

Image Zoom Library

In this example, we will show you how to use the CreativeEditor SDK’s CreativeEngine to control and observe camera zoom via the scene API.

Functions#

getZoomLevel(): number

Get the zoom level of the scene or for a camera in the scene in unit dpx/dot. A zoom level of 2.0 results in one pixel in the design to be two pixels on the screen.

  • Returns The zoom level of the block’s camera.
setZoomLevel(zoomLevel?: number): void

Set the zoom level of the scene, e.g., for headless versions. This only shows an effect if the zoom level is not handled/overwritten by the UI. Setting a zoom level of 2.0f results in one dot in the design to be two pixels on the screen.

  • zoomLevel: The new zoom level.
zoomToBlock(id: DesignBlockId, paddingLeft?: number, paddingTop?: number, paddingRight?: number, paddingBottom?: number): Promise<void>

Sets the zoom and focus to show a block. This only shows an effect if the zoom level is not handled/overwritten by the UI. Without padding, this results in a tight view on the block.

  • id: The block that should be focused on.
  • paddingLeft: Optional padding in screen pixels to the left of the block.
  • paddingTop: Optional padding in screen pixels to the top of the block.
  • paddingRight: Optional padding in screen pixels to the right of the block.
  • paddingBottom: Optional padding in screen pixels to the bottom of the block.
  • Returns A promise that resolves once the zoom was set or rejects with an error otherwise.
enableZoomAutoFit(id: DesignBlockId, axis: 'Horizontal' | 'Vertical', paddingBefore?: number, paddingAfter?: number): void

Continually adjusts the zoom level to fit the width or height of a block’s axis-aligned bounding box. This only shows an effect if the zoom level is not handled/overwritten by the UI. Without padding, this results in a tight view on the block. No more than one block per scene can have zoom auto-fit enabled. Calling setZoomLevel or zoomToBlock disables the continuous adjustment.

  • id: The block for which the zoom is adjusted.
  • axis: The block axis for which the zoom is adjusted.
  • paddingBefore: Optional padding in screen pixels before the block.
  • paddingAfter: Optional padding in screen pixels after the block.
enableZoomAutoFit(id: DesignBlockId, axis: 'Both', paddingLeft?: number, paddingTop?: number, paddingRight?: number, paddingBottom?: number): void

Continually adjusts the zoom level to fit the width or height of a block’s axis-aligned bounding box. This only shows an effect if the zoom level is not handled/overwritten by the UI. Without padding, this results in a tight view on the block. Calling setZoomLevel or zoomToBlock disables the continuous adjustment.

  • id: The block for which the zoom is adjusted.
  • axis: The block axis for which the zoom is adjusted.
  • paddingLeft: Optional padding in screen pixels to the left of the block.
  • paddingTop: Optional padding in screen pixels to the top of the block.
  • paddingRight: Optional padding in screen pixels to the right of the block.
  • paddingBottom: Optional padding in screen pixels to the bottom of the block.
type ZoomAutoFitAxis = 'Horizontal' | 'Vertical' | 'Both';

The axis(es) for which to auto-fit.

disableZoomAutoFit(blockOrScene: DesignBlockId): void

Disables any previously set zoom auto-fit.

  • blockOrScene: The scene or a block in the scene for which to disable zoom auto-fit.
isZoomAutoFitEnabled(blockOrScene: DesignBlockId): boolean

Queries whether zoom auto-fit is enabled.

  • blockOrScene: The scene or a block in the scene for which to query the zoom auto-fit.
  • Returns True if the given block has auto-fit set or the scene contains a block for which auto-fit is set, false otherwise.
unstable_enableCameraPositionClamping(ids: DesignBlockId[], paddingLeft?: number, paddingTop?: number, paddingRight?: number, paddingBottom?: number, scaledPaddingLeft?: number, scaledPaddingTop?: number, scaledPaddingRight?: number, scaledPaddingBottom?: number): void

Continually ensures the camera position to be within the width and height of the blocks axis-aligned bounding box. Without padding, this results in a tight clamp on the block. With padding, the padded part of the blocks is ensured to be visible. Disables any previously set camera position clamping in the scene and also takes priority over clamp camera commands.

  • ids: The blocks to which the camera position is adjusted to, usually, the scene or a page.
  • paddingLeft: Optional padding in screen pixels to the left of the block.
  • paddingTop: Optional padding in screen pixels to the top of the block.
  • paddingRight: Optional padding in screen pixels to the right of the block.
  • paddingBottom: Optional padding in screen pixels to the bottom of the block.
  • scaledPaddingLeft: Optional padding in screen pixels to the left of the block that scales with the zoom level until five times the initial value.
  • scaledPaddingTop: Optional padding in screen pixels to the top of the block that scales with the zoom level until five times the initial value.
  • scaledPaddingRight: Optional padding in screen pixels to the right of the block that scales with the zoom level until five times the initial value.
  • scaledPaddingBottom: Optional padding in screen pixels to the bottom of the block that scales with the zoom level until five times the initial value.
unstable_disableCameraPositionClamping(blockOrScene?: number | null): void

Disables any previously set position clamping for the current scene.

  • blockOrScene: Optionally, the scene or a block in the scene for which to query the position clamping.
unstable_isCameraPositionClampingEnabled(blockOrScene?: number | null): boolean

Queries whether position clamping is enabled.

  • blockOrScene: Optionally, the scene or a block in the scene for which to query the position clamping.
  • Returns True if the given block has position clamping set or the scene contains a block for which position clamping is set, false otherwise.
unstable_enableCameraZoomClamping(ids: DesignBlockId[], minZoomLimit?: number, maxZoomLimit?: number, paddingLeft?: number, paddingTop?: number, paddingRight?: number, paddingBottom?: number): void

Continually ensures the zoom level of the camera in the active scene to be in the given range.

  • ids: The blocks to which the camera zoom limits are adjusted to, usually, the scene or a page.
  • minZoomLimit: The minimum zoom level limit when zooming out, unlimited when negative.
  • maxZoomLimit: The maximum zoom level limit when zooming in, unlimited when negative.
  • paddingLeft: Optional padding in screen pixels to the left of the block. Only applied when the block is not a camera.
  • paddingTop: Optional padding in screen pixels to the top of the block. Only applied when the block is not a camera.
  • paddingRight: Optional padding in screen pixels to the right of the block. Only applied when the block is not a camera.
  • paddingBottom: Optional padding in screen pixels to the bottom of the block. Only applied when the block is not a camera.
unstable_disableCameraZoomClamping(blockOrScene?: number | null): void

Disables any previously set zoom clamping for the current scene.

  • blockOrScene: Optionally, the scene or a block for which to query the zoom clamping.
unstable_isCameraZoomClampingEnabled(blockOrScene?: number | null): boolean

Queries whether zoom clamping is enabled.

  • blockOrScene: Optionally, the scene or a block for which to query the zoom clamping.
  • Returns True if the given block has zoom clamping set or the scene contains a block for which zoom clamping is set, false otherwise.
onZoomLevelChanged: (callback: () => void) => (() => void)

Subscribe to changes to the zoom level.

  • callback: This function is called at the end of the engine update, if the zoom level has changed.
  • Returns A method to unsubscribe.

Settings#

Full Code#

Here’s the full code:

// Zoom to 100%
engine.scene.setZoomLevel(1.0);


// Zoom to 50%
engine.scene.setZoomLevel(0.5 * engine.scene.getZoomLevel());


// Bring entire scene in view with padding of 20px in all directions
engine.scene.zoomToBlock(scene, 20.0, 20.0, 20.0, 20.0);


// Follow page with padding of 20px in both directions
engine.scene.enableZoomAutoFit(page, 'Both', 20.0, 20.0, 20.0, 20.0);


// Stop following page
engine.scene.disableZoomAutoFit(scene);
// Query if zoom auto-fit is enabled for page
engine.scene.isZoomAutoFitEnabled(scene);


// Keep the scene with padding of 10px within the camera
engine.scene.unstable_enableCameraPositionClamping(
  [scene],
  10.0,
  10.0,
  10.0,
  10.0,
  0.0,
  0.0,
  0.0,
  0.0,
);


engine.scene.unstable_disableCameraPositionClamping();
// Query if zoom zoom clamping is enabled for the scene
engine.scene.unstable_isCameraPositionClampingEnabled();


// Allow zooming from 12.5% to 800% relative to the size of a page
engine.scene.unstable_enableCameraZoomClamping(
  [page],
  0.125,
  8.0,
  0.0,
  0.0,
  0.0,
  0.0,
);


engine.scene.unstable_disableCameraZoomClamping();
// Query if zoom zoom clamping is enabled for the scene
engine.scene.unstable_isCameraZoomClampingEnabled();


// Get notified when the zoom level changes
const unsubscribeZoomLevelChanged = engine.scene.onZoomLevelChanged(() => {
  const zoomLevel = engine.scene.getZoomLevel();
  console.log('Zoom level is now: ', zoomLevel);
});
unsubscribeZoomLevelChanged();