uImage Functions

uImage functions enable you to create personalized images dynamically during composition. These functions leverage Adobe Photoshop templates to generate customized graphics based on recipient data, allowing for sophisticated image personalization such as personalized product mockups, custom certificates, dynamic maps, and individualized promotional graphics.

Additional Resources: For comprehensive details on defining and generating personalized images, including template setup and configuration in uPlan, refer to the uImage online help. Video tutorials are also available at campus.xmpie.com.

uImage.uImage function

The uImage.uImage function creates personalized images from a Photoshop document package (.dpkg). This function processes the specially prepared Photoshop document contained in the package, generating a unique image for each recipient based on their data.

This function returns a Graphic asset that can be used in graphic ADORs.

Syntax

uImage.uImage(packageName, outputFolder, outputFilename, outputType, tagName, tagValue [, ...])

Parameter	Description
packageName	Required. The name of the Photoshop document package (.dpkg) to use as the template.
outputFolder	Required. Output folder. Leave empty ("") for default output folder.
outputFilename	Required. Output filename. Leave empty ("") to name automatically. Prepend with "OPT:" for optimization that avoids creating images that have already been created. (For example, when image with the same tagValues has already been processed.)
outputType	Required. Output format. (One of: "JPG", "EPS", "PSD", or "PNG".) The format can be followed by format settings, for example "JPG:Quality=8" (see Output format settings).
tagName	Required. Name of a tag or placeholder inside the Photoshop file.
tagValue	Required. Value to place into the Photoshop tag. In most cases, this will be the content object or variable containing the recipient firstname, company name or other data that is to be used in Photoshop.
Further tagName and tagValue pairs	Optional. Additional name/value pairs can be appended if the Photoshop template contains multiple tags.

Examples

Create personalized certificates with recipient name:

uImage.uImage("Certificate.dpkg", "", "", "JPG", "FullName", |->[FullName])

Result: Generates personalized certificate images using the recipient's full name in the designated text layer. Saved into the default output folder and named automatically.
Create product mockup images:

uImage.uImage("ProductMockup.dpkg", "", "OPT:" & |->[Product Name], "JPG", "product_code", |->[Product Code])

Result: Personalized product mockup images. Saved by the product name into the default output folder, and skipping duplicate product names.
Create personalized images with multiple data points:

uImage.uImage("IDCard.dpkg", "", "", "PNG", "Name", |->[EmployeeName], "Department", |->[Department], "Photo", |->[PhotoFile])

Result: Generates ID card images with name, department, and employee photo.

Note: The Photoshop document package must be properly configured in uPlan with defined variable layers before it can be used with this function. See the uImage online help for template preparation guidelines.

uImage.CreateImage2 function

The uImage.CreateImage2 function creates personalized images directly from a standalone Photoshop (.psd) template. When you select a .psd file with Browse in the rule editor's uImage settings, the rule editor creates this call for you (see Rule Editor). This function cannot be used in a document connected to uProduce or Circle.

This function returns a Graphic asset that can be used in graphic ADORs.

Note: It is recommended to use a Photoshop document package and the uImage.uImage function instead of using a Photoshop file directly. The Photoshop document package includes the Photoshop file together with any fonts, actions, and other information to ensure smooth production and avoid errors from missing components.

Syntax

uImage.CreateImage2(templateName, outputFolder, outputFilename, outputType, openingAction, closingAction, copyFittingMode, copyFittingMethod, tagName, tagValue [, ...])

Parameter	Description
templateName	Required. The name of the Photoshop file to use for image generation.
outputFolder	Required. Output folder. Leave empty ("") for default output folder.
outputFilename	Required. Output filename. Leave empty ("") to name automatically. Prepend with "OPT:" for optimization that avoids creating images that have already been created. (For example, when image with the same tagValues has already been processed.)
outputType	Required. Output format. (One of: "JPG", "EPS", "PSD", or "PNG".) The format can be followed by format settings, for example "EPS:Encoding=ASCII" (see Output format settings).
openingAction	Required. Name of an action or script to use when the Photoshop file is first opened and before adding tag values. (Use "NO" for no action, "ACN=folder\\action" for an action, or "SCR=C:\\folder\\script.js" for a script.)
closingAction	Required. Name of an action or script to use after tag values are added and before the Photoshop file is closed. (Use "NO" for no action, "ACN=folder\\action" for an action, or "SCR=C:\\folder\\script.js" for a script.)
copyFittingMode	Required. Copyfitting mode. "NO" (or "OFF") = none, "OF" = overflow, "UF" = underflow, "B" = both underflow and overflow, "M" = manual. See Copyfitting.
copyFittingMethod	Required. Copyfitting method. "HS" = horizontal scale, "FS" = font size. Ignored when the mode is "NO" or "M".
tagName	Required. Name of a tag or placeholder inside the Photoshop file. For a text tag, use the tag's name without the angle brackets that mark it in Photoshop. For an image tag, use the name of the tag's Smart Object layer. Tag names are not case-sensitive. A tag whose name does not match the template is not personalized, and the image shows the tag's placeholder.
tagValue	Required. Value to place into the Photoshop tag. In most cases, this will be the content object or variable containing the recipient firstname, company name or other data that is to be used in Photoshop.
Further tagName and tagValue pairs	Optional. Additional name/value pairs can be appended if the Photoshop template contains multiple tags.

Examples

Create a personalized promotional image:

uImage.CreateImage2("PromoTemplate.psd", "", "", "JPG", "NO", "NO", "OF", "HS", "firstname", |->[FirstName])

Result: A personalized promotional graphic using the recipient's first name, with no opening or closing scripts, and horizontal scaling applied only if the name overflows the tag in Photoshop.
Create a personalized product image with customer name:

uImage.CreateImage2("C:\\Templates\\ProductLabel.psd", "C:\\Output", "OPT:Label_for_" & |->[CustomerName], "EPS", "NO", "NO", "NO", "HS", "customername", |->[CustomerName])

Result: Generates a product label EPS graphic with the customer's name, no copyfitting and saving the output into a specific folder including the customer name in the filename and optimized to avoid duplicate work.
Create a personalized banner with multiple elements:

uImage.CreateImage2("WebBanner.psd", "", "", "PNG", "NO", "NO", "OF", "FS", "firstname", |->[FirstName], "code", |->[OfferCode], "expiry", |->[ExpiryDate])

Result: Generates a web banner personalized with name, offer code, and expiration date.

Copyfitting

Copyfitting handles personalized text that does not fit its text frame in the template. Text overflows when it is longer than the frame allows, and underflows when it leaves extra blank space. For example, the name "Jo" fits a frame that "Christopher" overflows.

The copyFittingMode parameter sets which cases are handled:

"NO": The text is not adjusted.
"OF" (overflow): Text that is too long is reduced to the maximum size allowed by the template. Shorter text is left unchanged.
"UF" (underflow): Text that is too short is enlarged up to the maximum size allowed. Text that is too long is left unchanged, so this mode is rarely used.
"B" (both): The text is stretched or condensed so that it is exactly the maximum size allowed.
"M" (manual): Copyfitting is set separately for each text layer in the template. Each text layer that needs copyfitting ends its layer name with the mode and method in square brackets, for example [OF,HS].

The copyFittingMethod parameter sets how the text is resized:

"HS" (horizontal scaling): The text is condensed or expanded horizontally. The font looks narrower or wider than designed, but its height stays the same, so the text never spreads above or below its frame.
"FS" (font size): The font is scaled proportionally, so it is not distorted, but its height varies with the text length. When underflow is handled, the larger text can spread above or below its frame. The minimum and maximum font sizes are defined in the template.

Output format settings

The outputType parameter of uImage.uImage and uImage.CreateImage2 can follow the format with settings, in the form "FORMAT:Setting=Value,Setting=Value", for example "EPS:Vector=False,Encoding=ASCII". Setting names are not case-sensitive, and a setting you leave out takes its default. For uImage.uImage, when you choose the format and its options in the rule editor's uImage settings, the rule editor writes this string for you.

Format	Setting	Values
JPG	Quality	1 to 12. The higher the value, the higher the quality. Default: 12.
EPS	Vector	True saves the image's vector data. Default: True.
EPS	Encoding	The format in which the image data is saved: Binary (default), ASCII, JPEGLow, JPEGMedium, JPEGHigh or JPEGMaximum.

Template Preparation

Before using uImage functions, templates (or document packages) must be prepared in Adobe Photoshop. Refer to the uImage online help or the following tutorials and training for more information.

Tutorials and training

How to create font-based uImage effects

How to use a Photoshop document package with uCreate Print

How to use uImage with uPlan

Using multiple text layers in uImage

Creating Image or picture font effects with uImage

Using Photoshop actions with uImage

Optimizing uImage performance