You are here

Text Merge Script

I am after a way of merging a delimited file against a xcf, and having several text fields change based on the merge file. I print custom shirts, and each image has a few text layers with a person name, athlete number and club etc. Rather then change each field manually, then save as personsname.jpg i would like to automate this, or atleast speed it up.

I have done a search, but could not find anything. I did find you can open a xcf in a text editor and change the text field values in that editor, so I guess its possible outside of GIMP if needs be.

Anyone else addressed this situation before? Any existing scripts or suggestion on how I could approach this?


Thanks Rod for the suggestion. Not quite what I need.

Maybe a better description of the need is:
I have a text file with 30 rows, each row has 3 comma seperated values.

In a master XCF file, I have many layers, including 3 text layers, with text values of xxxx,yyyyy,zzzz respectively.
I need to create 30 xcf files ( mary.xcf,rod.xcf,john.xcf)
The file mary.xcf would contain the three text layers, with values mary,red,happy, rod.xcf would have rod,blue,sad and john.xcf have john,yellow,angry text.

So, the find and replace would work well, but I need to find and replace multiple different fields, and also do this to quite a few times.

I am looking to automate/reduce the time needed, to complete this, and read in a text file as input.

Possible? A few other suggested scripts/plugins that might be of use?

I wrote a script[1] a few years back which created nametags based on a template XCF file and a data file containing the names. Give me a few days and I will try to adapt it to your scenario.


Is this it?

A friend just referred me to this today...looks like you have done this before and helped others out too!!!!

I was going to try this tonight and see what gives....

this script failed ( see ) but I think it is pretty close to what I need....i did post my comments in that forum. I think having a look at this script again and my error may the easiest way to go saulgoode, what do you think?

I have completed a draft version of your script. I won't have time to work on it further (or even explain it) until this weekend but if you want to try playing with it and figuring it out on your own, it is posted on my Fossil repo (there is an example data file and some comments in the script). (click on the most recent check-in and then on the "files" link)

saulgoode - thanks! OK, I could not get it to work, but thats probably more my ignorance then anything else! If you are willing to update it and explain it, I would be most grateful. I hope to be able to adapt this to different xcf files and data imports over time ( different shirt designs have different merge fields ) but this looks like it will be really cool!

Please elucidate on how it does not work. (Note: the open template image does not change, only evidence of "working" is creation of the files on disk.)

Also, if you could provide an example template image and some sample data for your task...

... and tell me what operating system you are using...

Of course....

Data file is in C:\Users\ian\Documents\exampledata.txt

Data file is exactly the same as you provided. ( manchester united etc )

Script is exactly as supplied, and in C:\Users\ian\.gimp-2.8\scripts\sg-goobie.scm

template is test1.xcf in C:\Users\ian\Documents\test1.xcf

template has 4 text layers - athlete-name club-name athlete-number uniform-color

Gimp is 2.8

OS is Windows 7


To test, I started GIMP, opened test1.xcf, Filters, Script-Fu, Console Browse, and then type this and hit enter:

Welcome to TinyScheme

Copyright (c) Dimitrios Souflis

Script-Fu Console - Interactive Scheme Development

> (script-fu-sg-goobie run-1 C:\Users\ian\Documents\test1.xcf C:\Users\ian\Documents\exampledata.txt C:\Users\ian\Documents\ sans 100 ffffff)

Error: ( : 1) eval: unbound variable: run-1

No files are created in the C:\Users\ian\Documents.

Having never run a GIMP script before ( other then GUI ones that come with GIMP ) I am sure there is lots wrong with my steps! I am very new to this and appreciate your help.  I have been manually updating xcf files for each custom shirt order.  

(As an added extra thing to think about, ones I have the xcf file,I was using Daves Batch Processor to convert to flattened JPG files (I print from another program that uses jpgs best ).  This is quick, but could also be done in this script if possible - it would cut out another step. Just a thought.)

Try running the command ("Goobie (uniforms)") at the bottom of the FILE menu.

well that would help!!!!!!! I just ran it over 48 rows, and it looks like the xcf all came out fine . Thanks so much saulgoode. I will now set up my real xcf files, and run it on them by modifying the script. Some of my shirt designs have one field to merge, others have four text layers, filled from three values ( two fields use the same text ), and a few other variations. So I want to learn how to tweak the script as I need. I will report back this weekend.

The last thing i do is convert via batch the xcf to jpg, so adding that as an option ( tick box? ) to the script would be super, but thats really a nice to have, not a need to have.

The text layers are different colours, so whilst its working on my actual xcf file, this highlights the fact I need some text layers which are black, and another white as its written on black background. Can the layer just inherit the current text color and not base it on a selection?

I tried commenting out (gimp-context-set-foreground color) by changing it to ;; (gimp-context-set-foreground color)
The result is all text is set to black, regardless of what color is selected. Can the the color selection be skipped altogether, or based on the current color used in the text layer?

It is feasible to retrieve the desired color from the text layer, though to be clear, the layer that determines a field's boundaries (I call these "frame layers") does not have to be a "text layer" in the GIMP sense. In fact, it is probably desirable it not be a text layer so that its dimensions correctly outline the field's location and size (if you resize a text layer then it becomes a bitmap layer).

The color of a "frame layer" could be determined by the following (or somesuch):

save the selection (if necessary)
alpha to selection on the frame layer
get the 'color' from the list of the mean values of the red, green, and blue channels.
restore the saved selection (if necessary)

This approach will still work if the frame layer IS a text layer, however, it will not work if the frame layer is multi-colored.

I will try to address this on the weekend (as well as saving to JPG). If you have any other thoughts on modifications, don't be reticent. The hardest part of writing scripts such as this is determining what the script needs to do; how to do it is generally trivial.

The script is working well - i have downloaded the new version which you might still be working on. I have noticed that selecting xcf file output > png format, but jpg > jpg and png > png OK.

The colour option is working great - i like how the FG option is implemented.

I can see a need developing to include carriage returns in text fields, but I am not sure I can define that requirement yet - I think I might use the script a bit, and see if this becomes a real need.

I then thought, and this is really not needed for what I can see I will use it for, but having the same option for the font selection would make this util more flexible and useful down the track. Sometimes you have more then one font in a file.

Fixed XCF extension.

Added command to specify the font for a particular layer (right-click on the layer's thumbnail preview and run "Goobie Set Template Font..." command). This is not ideal since there is no visual indication of what the current font of a layer is.

Note that if you are using GIMP 2.6.10 or earlier, the font setting capability may not always work (see Bugzilla #572865). Update to a newer version.

working much better! Thanks so much saulegood.

I noticed a few things relating to font size. The percentage approach regaring the size of fonts, and removal ( or not maintaining ) other aspects of the font layer, such as font size, justify alignment, and adjust letter spacing cause results different to expected. Can the option to retain the font size, justify alignment, and adjust letter spacing be included.

As it stands, I can run the script and generate the merged files, but I must make them XCF, and adjust the four text layers for "justify alignment" and "adjust letter spacing", and then save as JPG.

This is still much quicker then generating each one by hand, but would be great to elminate this step.

I really appreciate what you are doing - i am reading your scripts too to work out how it works so i may maintain it later if needed.

PS - i am using this to make custom shirts. Send me your contact details and I will make you one as a thanks and post it to you, whever you are.

**edited so my feedback made sense, and showed respect to the effort provided to me.

I have been busy the last few days and unable to spend any time of this. I will try to address your concerns this weekend.

As far as any compensation is concerned, please just consider making a donation to the GIMP project (

Thanks saulegood. And yep, donation done :-)

Script tested on two records, and it worked well. I will be processing 50 or so this week, and will provide some full and proper feedback then.

Thanks a million.

I have updated the script. Little has changed except for allowing any combination of XCF, JPEG, and PNG outputs and that text attributes (font, font-size, color, etc) are always taken from the text layers in the template file. Horizontal justification (left, center, right) is also taken from these text layers. The text layer should be sized to match the boundaries of the frame on the uniform.

If the data string being substituted fits within the template layer frame boundaries then the original font-size is retained. If it exceeds the boundaries then the behavior is specified by the scripts "Font sizing (if too large)" parameter, which is one of "Fit", "Crop", or "Overflow". "Fit" will reduce the font size so as to have the text fit within the template frame, while both "Crop" and "Overflow" will keep the template's original font size.

An option is provided to specify the vertical alignment of the text within the field (Center, Top, Bottom), however, owing to variations in the way that different fonts are described, this alignment may not be precise (though it should be consistent across a particular batch run).

This latest version has not been rigorously tested, so let me know about any problems encountered. If further changes are to be proposed, it would be helpful to have a couple example template and data files to work with.

Subscribe to Comments for "Text Merge Script"