Variable Images Advanced

Script for Adobe Photoshop
Latest update 1/17/2023, version 3.3

This script is an advanced version of the Photoshop script Variable Images From CSV. Like the basic version, the script reads a CSV spreadsheet of multiple image names and text, and for each row of data, updates layer names that match column heads to the image or text specified. But unlike the basic version, this advanced version can also process multiple templates and multiple data files. Users of this advanced version are able to create thousands of unique images in a fraction of the time it would take manually, or even with the basic version of the script.

  • Combine images and text for personalized images
  • Update any number of image and text layers
  • Specify URLs to download image and import to layer
  • Output formats BMP, JPG, PNG, PSD, or TIF
  • Process multiple template images and data files
  • Saves results in subfolders for each template

Trial version available on request

Multi-user license

Before using the script

Using the script requires some preparation. First is a template image, or images, each with specific layer names.

Variable Images Advanced layers example   Variable Images Advanced template example

This example is two normal pixel layers, “image1” and “image2”, then three text layers, “text1”, “text2”, and “text3”. And one final normal pixel layer “logo”. Pixel layers may be masked as are layers “image2” and “logo” in this example.

The number of layers to update is limited only by the resources available to Photoshop. Layers may exist that are not updated. For example, elements common to all images output. Any layer name that does not appear in the spreadsheet is untouched and, if visible, is included with all images output.

Multiple template images can use the same layer names but different common elements, or the templates can use entirely different layer names. If layer names are common to all templates, a single data file works. When templates have different layer names, each needs its own data file that assigns content to the matching layer names. The script allows using either method, explained in the section How to use the script.

The second item to prepare is one or more spreadsheets of image file names and text. The column heads must match layer names in the template images. This tells the script what goes where. If column heads exist that have no matching layer in the template image, the columns are ignored.

Variable Images Advanced data example

In this example, rows of the column “image1” are image file names to import and update the layer named “image1” of the template image. Rows of the column “text1” replace the text contents of the layer named “text1”.

And so on with all layer names and column heads present in both the template and data.

Columns for images may be the full path to the file, a URL to download the file, or the file name only. If file name only, select the folder to search for images in the section Images. It is possible to mix image names that are full paths and/or URLs with images that are file name only. See the section Further reading for more details.

There is one special column head that is optional and not related to any layer name. Use the column head “file name” to indicate the output file name. If this column is absent, the first image name or text value found is used to name the output file.

Once the spreadsheets are ready, save each as Comma Separated Values (CSV format). From Excel, choose Save As, and in the drop-down list Save as type, select CSV UTF-8 Comma delimited. UTF-8 is recommended so any Unicode characters are preserved.

How to use the script

The script may run with or without a template image open.

The interface has five sections: Template(s), Data file, CSV Delimiter, Images, and Output. Choose to process an open template, a list of templates, or a list of templates and data files. Optionally select a data file and/or images folder, and select the output folder. Enable the desired options and click the OK button to begin. If any problems occur, a log file is written in the output folder, and the user is notified.

Section 1: Template(s)

Active image — if a template image is open, select this option and the script works identical to the basic version Variable Images From CSV. Select the data file, delimiter, and whether to search a folder for images.

Templates list (TXT) — this choice is one of two methods to process multiple templates. Choose this option and select a text file that lists the full paths to multiple template files. The script does not impose a limit on the number of templates that are processed.

Variable Images Advanced template list example

For each template image found in the list, the template image is opened, and the script processes the data file selected in the section Data file. This is repeated for every line of the templates list. Note that full paths are required, and even for Windows, forward slashes are acceptable because ExtendScript recognizes them as path separators regardless of the platform.

Templates + data files list — this is the second method of processing multiple templates, and includes processing multiple data files, each specific to a particular template image. This requires another spreadsheet is prepared and saved as Comma Separated Values (CSV). The script does not impose a limit on the number of template/data file pairs that are processed.

Variable Images Advanced template+data file list example

IMPORTANT: this CSV data file does not use headers. Template/data file pairs to process begin at row 1 rather than row 2, typical for data that has column headers.

For each row of the data, starting at row 1, the script expects the first column is a template image that is opened, then the script processes the data file in the second column of the row. This is repeated for every row of the templates+data list. Note that full paths are required, and even for Windows, forward slashes are acceptable because ExtendScript recognizes them as path separators regardless of the platform.

Section 2: Data file (CSV)

File — select the CSV data file. When the template option Templates + data files list is selected, this option is disabled as it is irrelevant.

Section 3: CSV Delimiter

The character that separates columns of data files and the CSV file when the template option Template + data files list is selected.

Comma — the default, normal in the United States.

Semicolon — Some European countries use semicolon rather than comma.

Select the delimiter used in your region of the world.

Section 4: Images

Data for images is full path or URL (or there are no images) — when image columns in the data are full paths to images or URLs, there is no need to select a folder where they are located. Likewise, if the data is only text to update, a location to search for images is irrelevant. In these cases, choose this option, and the button Folder is disabled.

Data for images is the file name only, located in folder below — without a full path to images, the location to search for them is needed. Use the button Folder to select a location.

Folder — select a folder to search for images. The script processes each image file in the spreadsheet data that matches a file found in this folder.

Section 5: Output

Folder — select the location to which images are output.

Format — select the file format to output. Choices are BMP, JPG, PNG, PSD, or TIF.

Flatten — the result is a single “Background” layer. BMP and JPG always perform this step.

Single merged layer — applies to formats PNG, PSD, and TIF. When enabled, hidden layers are discarded, and the remaining layers are merged to a single layer. If a layer mask remains, it is applied. PNG does not support multiple layers, so this step always occurs if not flattened. The option does not apply to BMP or JPG as both do not support transparency and must be flattened.

The options Flatten and Single merged layer are mutually exclusive. Choose one or the other, or neither. The script does not allow both.

Quality — applies to JPG format only. Valid range is from 0 to 12. 0 is extreme compression resulting in low quality. 12 is light compression that is virtually indistinguishable from the original, the highest possible quality, which of course, results in the largest file size. 10 to 12 is recommended for print or other high-quality reproduction. For web images, 5 to 8 is an acceptable range.

Convert to profile — converts color to the selected profile prior to output. Note that BMP and PNG formats are always converted to sRGB web standard, and the option to select otherwise is disabled.

Further reading

If you’ve reached this point, you know enough to use the script. The remainder is not crucial to read, but helps understand how the script works. This section is last, in the interest of minimizing “Too Long; Didn’t Read” (TL;DR).

For unmasked pixel layers, each imported image is scaled to match the template image size and centered and cropped as needed to maintain proportions. For pixel layers that are masked, the imported image is scaled to fit center inside the mask, and excess image is masked out as needed to maintain proportions. All image layers are converted to smart objects, then the layer contents are updated. If the layer is a normal pixel layer and effects are applied, the effects are copied and pasted back to the layer after converted to a smart object. For layers already smart objects, any layer effects remain.

For text layers, the contents are replaced, and any layer effects remain. If the text content might span multiple lines, use a text area rather than single line to define the placeholder. Do this by dragging the cursor to define the text area rather than simply click, which limits text to a single line. Using a text area is preferred because it adapts to single or multiple lines of content as needed. Single line text placeholders do not.

At this time, the replacement of text on a path is unreliable due to a bug in Photoshop that shifts the path position when altered by ExtendScript.

Regarding image full path versus file name only. It is possible to mix full paths, URLs, and file names only in the data file. Use the option Data for images is the file name only, and select a folder to search for images. Images that are file name only work as expected. Images that are full paths of course fail once prefixed with the path to the images folder, but the script doesn't immediately give up. Instead, the script tests if a file exists without the images folder prefixed. If a file is found, the script uses it and adds an alert to the log file. Images that begin with http are considered URLs and are not altered. The image is downloaded to the output folder, imported into the template, then deleted.

It is the responsibility of the user to ensure column heads match the correct kind of layer in the template image. If a column for file names matches the name of a text layer, the text content is updated to the file name. If a column for text matches the name of a pixel layer, the script reports “File not found” in the log, unless somehow, however unlikely, the text matches the name of a file in the images folder.

Converting color requires the image is flattened or merged to a single layer because the possibility of adjustment layers, which cannot change color space and maintain faithful results. For this reason, when Convert to profile is enabled, the script ensures either Flatten or Single merged layer is enabled.

TIP: Converting to another profile is primarily to make CMYK separations for print, which of course is functionality the script provides. But as well, this option can convert duotones to RGB or CMYK, or convert these and other color spaces to grayscale (use the profile Dot Gain 20%).

The formats JPG, PSD, and TIF always embed color profiles. BMP and PNG never embed color profiles.

Available color profiles

For the option Convert to profile, the list of profiles from which to choose is compiled by searching known locations in the system for .icc/.icm files and extracting the profile name. This occurs each time the script is launched. The list should include most of the same profiles Photoshop displays in dialogs such as Color Settings, but it doesn’t match exactly. If a needed profile does not appear in the list, add the profile to a location both Photoshop and the script look for profiles (below), and relaunch the script.

macOS

:Library:ColorSync:Profiles

Windows

\Windows\System32\spool\drivers\color

Language

By default the script language is US English, which does not require further download or configuration. To have the script interface display other languages, choose from the available languages below. Download and copy the .i18n file to the script folder alongside the script. When launched, the script detects the language file and displays interface text in that language. If your language is not listed, download the English file and translate it. The file is plain text formatted as JSON, containing interface text in English, and a second value for its translation, which for the English file is the identical text. Copy the file and rename it to replace “en” with the relevant code for your language, then edit the file to change each line’s second value to the translation in your language. For more detailed instructions of how to edit and install i18n files, see How to Localize Scripts.

English: variable-images-advanced-en-i18n.zip

Trial version available on request

Multi-user license

Change log: variable-images-advanced.txt

For help installing scripts, see How to Install and Use Scripts in Adobe Creative Cloud Applications.

Custom solutions based on any script, or completely new ideas, are possible at reasonable cost. Contact William for more information.

IMPORTANT: by downloading any of the scripts on this page you agree that the software is provided without any warranty, express or implied. USE AT YOUR OWN RISK. Always make backups of important data.

IMPORTANT: fees paid for products purchased from this site, or for programming custom solutions, are the purchase of a non-exclusive license to use the software and do not grant the purchaser any degree of ownership of the software. Author of the intellectual property and copyright holder William Campbell retains 100% ownership of all code used in all products and custom solutions.

IMPORTANT: scripts are developed for the latest Adobe Creative Cloud applications. Many scripts work in CC 2018 and later, even some as far back as CS6, but may not perform as expected, or run at all, when used in versions prior to 2018. Photoshop features Select Subject and Preserve Details 2.0 definitely fail prior to CC 2018 (version 19) as the features do not exist in earlier versions. For best results use the latest versions of Adobe Creative Cloud applications.