Variable Images Advanced
Script for Adobe Photoshop
Latest update 8/23/2023, version 4.4
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, and each output file full path can be specified. 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.
- Process multiple templates and data files
- 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
- Saves results in subfolders for each template
NOTE: after video production, new features have been added in response to user feedback. 1. the template option Template column in data file. 2. the image option Image placement. 3. the output option Output file is full path. See instructions below for details.
Before using the script
Using the script requires preparation. First is a template image, or images, each with specific layer names.
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.
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. When the template image contains multiple layers of the same name, all are updated with the content specified in the data for the layer name.
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, which is then saved in the selected output folder. If this column is absent, the first image name or text value found is used to name the output file. Optionally, the value of this column may be the full path to the output file, in which case an output folder is irrelevant. For more details, see the section Output.
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 the template method, the data and delimiter, how to access images, and the output options. When ready, click the OK button to begin. If any problems occur, a log file is written 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.
Template column in data file — the first of three methods to process multiple templates. When this option is chosen, the data file selected in the section Data file must have a column 'template'.
Under the template column, in each row list the full path to the template file to use for that row of data. Each row may use the same template or a different template. There is no limit of the number of templates that may be processed. For best efficiency, group rows using the same template together because the script keeps the same template file open until the next row calls for another. 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 list (TXT) — the second method of processing multiple templates. Choose this option and select a text file that lists the full paths to multiple template files. There is no limit of the number of templates that may be processed.
For each template file in the list, the template 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 — the third method of processing multiple templates, and includes processing multiple data files, each specific to a particular template. This requires another spreadsheet is prepared and saved as Comma Separated Values (CSV). There is no limit of the number of template/data file pairs that may be processed.
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 file to open, 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.
Image placement — determines how imported images are scaled. All images are first centered relative to the canvas or layer mask, if one is applied to the layer. Fill then scales the image so its shortest dimension reaches the canvas or mask boundary and crops out any portion that exceeds the boundary. Fit scales the image so its longest dimension reaches the canvas or mask boundary and none of the image is cropped. The options Fill and Fit maintain proportions. The option Stretch scales images non-proportionally so that both dimensions fit the canvas or mask. For imported images that match the aspect ratio of the canvas or mask, the image is scaled precisely to the canvas or mask size, and these options have no effect.
Section 5: Output
Output file is full path — for data that includes the column “file name”, the column lists the full path to the output file.
Output file is name only save to folder below — for data that includes the column “file name”, the column lists the file name only, which is saved in the folder selected below.
Folder — select the location to which images are output.
Template subfolders — when enabled, images are output to a subfolder the template name. Disable to have all images output to the same folder. Template subfolders are required when processing a Templates list because a single data file is used for all, which otherwise lets images from the last template overwrite images from all prior templates. Even when not processing a template list, this is still a concern. If template subfolders are disabled, any file name, or layer name used to name output files, found in data files and used to name images must be unique. Any that are the same, the last image output overwrites earlier files of the same name. It is recommended that template subfolders remain enabled. Only when confident all file names are unique should it be disabled.
Replace existing output files — when enabled, existing output files are replaced. When disabled and an existing file is detected, an incremental number is added to the file name to prevent overwriting the existing file.
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.
If you’ve reached this point, you know enough to use the script. The remainder is not crucial to read, but it helps understand how the script works. This section is last, in the interest of minimizing “Too Long; Didn’t Read” (TL;DR).
Each image imported is centered relative to the target layer then scaled based on the option Image placement. If set to Fill and the layer is unmasked, the imported image shortest dimension is scaled to match the canvas size and excess image is cropped out. For layers that are masked, the imported image shortest dimension is scaled to fit inside the mask and excess image is masked to hide it. If set to Fit and the layer is unmasked, the imported image longest dimension is scaled to match the canvas size and none of the image is cropped. For layers that are masked, the imported image longest dimension is scaled to fit inside the mask, and because none of the image is masked, all of the image appears. The option Stretch scales images non-proportionally so that both dimensions fit the canvas or mask.
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.
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.
FREE 30 DAY TRIAL
Change log: variable-images-advanced.txt
For help installing scripts, see How to Install and Use Scripts in Adobe Creative Cloud Applications.
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.
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.