In-preview image editing


By default web-to-print image fields only replace the placeholder image with a user image. ZetaPrints web-to-print may change the appearance of the image automatically (rotating, filters, etc) to match the placeholder. This post explains how to add image manipulation metadata for user-defined editing, such cropping, shift, resizing, etc.

Web-to-print metadata fields

Web-to-print image fields always begin with #(hash) followed by the field name, e.g. #Photo or #Your photo.

Metadata fields have the same name as the field they correspond to with an added * at the begging:

Example#Photo (image field name), *#Photo (metadata field name)

The fields should be sent in POST part of the request. Only one optional metadata field per image field is expected.

Understanding of shapes coordinates system and shape coordinates for editing is required before proceeding to the rest of the post.

Metadata parameters

Parameters are name value pairs separated by ; (semicolon). E.g. sh-x=0.3;sh-y=0.75;col-o=#aabbcc

Required parameter

  • img-id=[guid of the image the rest of the parameters apply to]

You must provide the image ID with the rest of the parameters. E.g *#Photo must have the same image ID as in #Photo to make sure that stepping back and forth didn’t result in applying parameters to a wrong image. It is possible if the state of the request is out of sync with the user cache in ZetaPrints.


Parameter names: sh-x, sh-y

Allowed values: -10.0 < value < 10.0, decimal, relative to the page size.

The value is the ratio of the shift to the page size as specified in the template details XML. Positive values – shift down and right, negative – shift up, left. Zero – no shift.

Invalid values are ignored. Use shift params if you want a shape to be shifted exactly without altering the size at all for consistency.


  • sh-x=0.3;sh-y=0.75 – shifts by 30% to the right and 75% down
  • sh-x=-0.5;sh-y=-0.2 – shifts by the 1/2 page width to the left and 1/5 page height up


Parameter names: sz-x, sz-y

Allowed values: 0 < value < 10.0, decimal, relative to the original shape size.

The value is the ratio of the new size to the size of the placeholder shape as specified in the template details XML.

  • 0 < value < 1 – decrease size by value
  • 1 < value < 10 – increase size by value
  • value = 1 – no change

Invalid values are ignored. Use size params if you want the size of the shape to change while keeping it anchored at the same place for consistency.


sz-x=0.3;sz-y=0.75 – decrease width to 30%, height to 75%

sz-x=1.1;sz-y=0.2 – increase width to 110%, decrease height to 20%


Parameter names:

  • cr-x1, cr-y1 – top left corner
  • cr-x2, cr-y2 -bottom right corner

Allowed values: 0 <= value <= 1

No cropping is done if any of the values is incorrect or missing. The minimal size of the cropped image is 10px * 10px.


  • cr-x1=0.1;cr-y1=0.15;cr-x2=0.9;cr-y2=0.95 – crop 10% on the left, 15% at the top, 10% on the right and 5% at the bottom
  • cr-x1=0;cr-y1=0;cr-x2=0.7;cr-y2=0.8 – crop 30% on the right and 20% at the bottom
  • cr-x1=0;cr-y1=0;cr-x2=1;cr-y2=1 – nothing to crop, values ignored

New coordinates

Shift and resize can be combined into a single set of new shape coordinates: x1, y1, x2, y2.

  • x1, y1 – top left corner
  • x2, y2 -bottom right corner

The coordinates are expressed in the same relative units the original shape coordinates were expressed. All four parameters must have valid values. Shift and resize parameters are ignored if the new coordinates are provided. Use these params if the user performed a free-form shift / resize operation.

Parameter processing

Web-to-print image field processing is a sequence of steps on ZetaPrints side:

  1. crop the user image using metadata parameters
  2. replace the placeholder with a user image
  3. recalculate alignment, rotation and other properties to match the placeholder
  4. apply new coordinates (exit if successful)
  5. apply shift from the metadata
  6. apply resizing parameters from the metadata

If is better to combine shift and resize into new coordinates.

See also: