countersheets extension (counters, cards, mail merge from CSV)

Other sites and resources for Inkscape users.
pelle
Posts: 53
Joined: Wed Mar 05, 2008 8:23 am

countersheets extension (counters, cards, mail merge from CSV)

Postby pelle » Sun Jul 22, 2018 10:16 pm

Just tagged my now over 10 years old countersheets extension as version 2.1. Draw templates as groups in Inkscape, then read data from a CSV file and you get new layers with sheets of "counters" (or whatever it is that you want to do; it is kind of a generic mail-merge tool really, but it has some special features like the registration marks that were made to make nice printed single or double-sided sheets of cardboard tokens for playing boardgames, or to make sheets of playing cards, but you could of course do sheets of anything else as well and the name of this extension should probably change at some point...).

https://github.com/lifelike/countershee ... es/tag/2.1

Some changes since 2.0.2:
- bleed
- inline images in text
- sheet backgrounds
- simple text styles (bold and italics)
- import text from external text files (instead of having everything in the spreadsheet)
- outline registration mark rectangles
- registration marks optionally going all the way across sheets
- one-sided sheets option (both front and back on the same sheet)
- dimensions with units in dialog entry fields
- many bug fixes

See the wiki for installation instructions and full changelog and some tutorials etc: https://github.com/lifelike/countersheetsextension/wiki

Moini
Posts: 3293
Joined: Mon Oct 05, 2015 10:44 am

Re: countersheets extension (counters, cards, mail merge from CSV)

Postby Moini » Mon Jul 23, 2018 12:09 am

Can you post a link to your extension into the gallery at inkscape.org? See https://inkscape.org/en/develop/extensi ... -extension for instructions.
Something doesn't work? - Keeping an eye on the status bar can save you a lot of time!

Inkscape FAQ - Learning Resources - Website with tutorials (German and English)

Moini
Posts: 3293
Joined: Mon Oct 05, 2015 10:44 am

Re: countersheets extension (counters, cards, mail merge from CSV)

Postby Moini » Mon Jul 23, 2018 12:11 am

... what is a mail merger, btw.? (and what is a countersheet?)

Is this similar to the Generator extension? http://wiki.inkscape.org/wiki/index.php ... #Generator
Something doesn't work? - Keeping an eye on the status bar can save you a lot of time!

Inkscape FAQ - Learning Resources - Website with tutorials (German and English)

Moini
Posts: 3293
Joined: Mon Oct 05, 2015 10:44 am

Re: countersheets extension (counters, cards, mail merge from CSV)

Postby Moini » Mon Jul 23, 2018 12:13 am

See, I think this is really useful for a lot of purposes, but I don't really get what exactly it does, because of the terminology you are using. Maybe giving some examples and phrasing it in a way that non-developers can understand would help users looking for something like this a bit.
Something doesn't work? - Keeping an eye on the status bar can save you a lot of time!

Inkscape FAQ - Learning Resources - Website with tutorials (German and English)

pelle
Posts: 53
Joined: Wed Mar 05, 2008 8:23 am

Re: countersheets extension (counters, cards, mail merge from CSV)

Postby pelle » Mon Jul 23, 2018 7:33 pm

It is not so much technical terminology as boardgames terminology. :)

You draw something in Inkscape, and then you want to make many copies of it in the same document, but each copy has to be slightly different (texts modified or colors changed or really any SVG attributes modified) and possibly you might want to arrange the copies in very specific ways instead of just one big rectangle full of copies. So you open excel or your other favourite spreadsheet application and type in all the information about what copies you need and what is special about each copy (the text and colors etc) and then you use this extension to put everything together.

The extension was originally made just for making sheets of this kind of counter:
https://en.wikipedia.org/wiki/Counter_(board_wargames)

Then I and others started using it also to make cards for card games. Some have used it for other things as well.

Only later did I learn that what it does is essentially what office applications call "mail merge". Microsoft has written an introduction about it here (first hit on google): https://support.office.com/en-us/articl ... 948fa3d7d3

Many desktop publishing and office applications have a feature like that. Adobe calls it Data Merge:
https://helpx.adobe.com/indesign/using/data-merge.html

pelle
Posts: 53
Joined: Wed Mar 05, 2008 8:23 am

Re: countersheets extension (counters, cards, mail merge from CSV)

Postby pelle » Mon Jul 23, 2018 8:27 pm

Moini wrote:Is this similar to the Generator extension? http://wiki.inkscape.org/wiki/index.php ... #Generator


Yes! The idea is fundamentally the same. I think I was in contact with the guy making that extension some time in the past. I do not know if the generator collates the things it generates into sheets or just output one file for each thing?

A big difference between my extension and traditional mail/data merge tools like Generator is that the entire input drawing (SVG) is not used as one big template. Instead you can have one or as many templates as you want to, each in its own group. And then you can use columns in the CSV (spreadsheet) to pick one or more templates to use for each copy ("counter") that is created. If you are making copies of a mail for mass-mailing, that is the stereotypical example for using a tool like that, then all you do is replace some text (e.g. the address and recipient name). But if you make something like a deck of cards for a game then you are likely to need to mix several different designs. And since some things are going to show up on different types of cards you also want the ability to layer different templates on top of each other. It gets a bit complex of course.

Generator and my extension have in common that the first row in the CSV is used to specify what each column is used for. It seems more common, like in inDesign, that you use some GUI in the application to specify what the columns are for instead. So sometimes you need to put some slightly technical/scary things in the column headers (e.g. "title[style:fill]=white", which means "set the fill style of the element with id title using values from this column, and the default if the cell is empty is white"). But usually the header is just a plain id (like in the Generator examples).

My main inspiration originally was a Windows application called nanDeck that is very popular with board game designers. It is a stand-alone application and comes with its own scripting language and own text-based graphics descriptions. I thought it would make much more sense to make a tool like that but basing it on standard file-formats and leverage the GUI and SVG-rendering already in Inkscape (and support more platforms). It was more by accident that my solution ended up looking like mail/data merge tools.

http://www.nand.it/nandeck/

Maybe it would make sense to fork my extension and try to make a variant that is more like a pure mail/data merge (like Generator but more features) and remove the board game stuff, and come up with a better name. But that is not something I have any plans to do right now.

But I rant too much. I was never very good at being economic with words. That also causes some problems in my documentation. The page describing how to make your own templates is horrible and way too long:

https://github.com/lifelike/countershee ... -Templates

Moini
Posts: 3293
Joined: Mon Oct 05, 2015 10:44 am

Re: countersheets extension (counters, cards, mail merge from CSV)

Postby Moini » Mon Jul 23, 2018 10:15 pm

Yes! Thank you, Pelle. These explanations are understandable. So it can replace colors, text etc., potentially even paths? Or is it limited to a subset of attributes? It seems to hold many hidden gems. Please, please share it on inkscape.org!

I think the second paragraph here (viewtopic.php?f=11&t=33895#p105491) provides a great summary.

What I remember about Generator is that it outputs many separate SVG files, I don't remember if it allows to arrange the output in a grid - don't think so, but not sure.

For your documentation, if you don't want to/can't invest time into rephrasing it, I believe some screenshots could be helpful.
Something doesn't work? - Keeping an eye on the status bar can save you a lot of time!

Inkscape FAQ - Learning Resources - Website with tutorials (German and English)

pelle
Posts: 53
Joined: Wed Mar 05, 2008 8:23 am

Re: countersheets extension (counters, cards, mail merge from CSV)

Postby pelle » Tue Jul 24, 2018 6:26 pm

Thanks!

It can replace any SVG attribute, however some are difficult to use. For instance if you set the transform attribute sometimes parts can end up all over the page (have on my TODO list that there needs to be a way to specify rotations and scales in a safe way). It should be possible to set a path, but usually it is probably easier to draw different paths and for instance use what Inkscape calls a clone (a SVG use element, behind the scenes) to replace a path with a different path.

https://github.com/lifelike/countershee ... iki/Clones

Only started to add images to the documentation a few days ago when I finally sat down to read up about how to add them in the GitHub wiki. Now that I know how it works I plan to add some now and then.

Moini
Posts: 3293
Joined: Mon Oct 05, 2015 10:44 am

Re: countersheets extension (counters, cards, mail merge from CSV)

Postby Moini » Wed Jul 25, 2018 1:01 am

The next time I see a question from someone asking how to programatically exchange items in their images, I'll point them to your extension :)
Something doesn't work? - Keeping an eye on the status bar can save you a lot of time!

Inkscape FAQ - Learning Resources - Website with tutorials (German and English)

wyatt121
Posts: 13
Joined: Wed Jan 03, 2018 8:15 am

Re: countersheets extension (counters, cards, mail merge from CSV)

Postby wyatt121 » Fri Jul 27, 2018 6:21 pm

Hi Pelle,

Great extension!. I'm very excited to try. I have been working with Inkscape command lines, and have become very frustrated with the inability to pass values on the command line. It seems I may be able to pass values with your extension and a CSV file. Here are the 3 things I'm trying to accomplish...

1. Change selected text object font size to a specific value
2. Scale selected paths to a specific size
3. Rotate selected objects by a specific value

Can I store these values in a CSV file, run your extension, and all my problems are solved? Say YES please! :)

Any help is very much appreciated.

Regards,

Wyatt

pelle
Posts: 53
Joined: Wed Mar 05, 2008 8:23 am

Re: countersheets extension (counters, cards, mail merge from CSV)

Postby pelle » Mon Jan 28, 2019 8:34 pm

Got a bunch of things fixed in this extension this weekend. Thinking of trying to not add any more features for a while and focus on documentation and bug fixes, then call it version 2.2. Tagged it as 2.2pre2 so you can download it and have a look:

https://github.com/lifelike/countershee ... n/releases

No huge new features since 2.1, but several bug fixes and included templates/examples.

Spacing option added. Set it to some length and all the generated components will be separated by that much, leaving room for bleed for instance.
https://github.com/lifelike/countershee ... ki/Spacing
Image

Options are now split up in many tabs as the list of options was getting too long for comfort.

When text is styled (bold or italics) the generated tspan or flowSpan elements now have predictable ids, so additional columns in the CSV can be used to add further style (or other attributes) to bold, italics, or inlined images (or even to completely override the bold or italics text style).
https://github.com/lifelike/countershee ... i/Set-Text

There is now a templates/counters.svg with some very oldschool counter layout examples (also some CSV files to use it with).
Image
Image
Image

pelle
Posts: 53
Joined: Wed Mar 05, 2008 8:23 am

Re: countersheets extension (counters, cards, mail merge from CSV)

Postby pelle » Mon Jan 28, 2019 8:38 pm

wyatt121 wrote:Hi Pelle,

Great extension!. I'm very excited to try. I have been working with Inkscape command lines, and have become very frustrated with the inability to pass values on the command line. It seems I may be able to pass values with your extension and a CSV file. Here are the 3 things I'm trying to accomplish...

1. Change selected text object font size to a specific value
2. Scale selected paths to a specific size
3. Rotate selected objects by a specific value

Can I store these values in a CSV file, run your extension, and all my problems are solved? Say YES please! :)

Any help is very much appreciated.


Hi. Sorry I do not login here often enough and I guess this is way too late, but if anyone else is wondering... The extension is not made to modify any existing things in the drawing, only create new copies of things. But if you are fine with that (i.e. a new copy being created that has the modified attributes) the things you ask for can almost be done. Problem is that transforms like scale and rotate are very difficult to get right. There needs to be some special support for that in the extension, and that has not happened yet, because the transforms must be combined with any existing transforms or elements are likely to end up all over the place.

The 1st one with font size should not be a problem at least. Untested but you should be able to set the font size like any other style attribute.
https://github.com/lifelike/countershee ... /Set-Style

Moini
Posts: 3293
Joined: Mon Oct 05, 2015 10:44 am

Re: countersheets extension (counters, cards, mail merge from CSV)

Postby Moini » Mon Jan 28, 2019 11:07 pm

Pelle, just a heads up: extensions will change massively for Inkscape 1.0.
A short and incomplete writeup is linked from here:

http://wiki.inkscape.org/wiki/index.php ... extensions
Something doesn't work? - Keeping an eye on the status bar can save you a lot of time!

Inkscape FAQ - Learning Resources - Website with tutorials (German and English)

pelle
Posts: 53
Joined: Wed Mar 05, 2008 8:23 am

Re: countersheets extension (counters, cards, mail merge from CSV)

Postby pelle » Tue Jan 29, 2019 6:23 am

Thanks for the heads up! It does not look too bad, but time will tell. Pretty used to having to rewrite things almost every minor release and can rarely support more than one or two recent versions of Inkscape. Hope the API can stabilize eventually, but I hope before then it will become more like a proper API with hooks into Inkscape internals instead of having to do the horrible parse-SVG-then-generate-new-SVG thing.

Regarding the new test requirements, in the soon 11 years since I first published this extension I have almost stopped using unit tests. There are still a few included and I run them now and then, but I rely almost completely on higher level end-to-end tests that I found are much, much better for catching errors and analyzing what is wrong. Also much easier to create and maintain. They are in the svgtests subdirectory of my extension if any developer wants to have a look. Just a simple python script to call the extension on the command-line with known input files and compare the results to saved expected output files. Can really recommend something like that to all extension developers (and that Inkscape does not insist on extensions to have unit tests specifically).

Moini
Posts: 3293
Joined: Mon Oct 05, 2015 10:44 am

Re: countersheets extension (counters, cards, mail merge from CSV)

Postby Moini » Tue Jan 29, 2019 8:31 am

They're working on making more functionality accessible to scripting, but it's still in early stages, as far as I understand.

I always do my own testing by hand, eye-to-eye, so to speak. It's sufficient for the small things I do.

I understand about the more professional way of automating that end-to-end test, it's going to capture everything.

You could try to suggest a change in paradigm to Martin, or to just implement a couple of those tests for Inkscape, explaining why you would recommend doing it differently. I think there was already someone else who suggested something similar.
Something doesn't work? - Keeping an eye on the status bar can save you a lot of time!

Inkscape FAQ - Learning Resources - Website with tutorials (German and English)

Moini
Posts: 3293
Joined: Mon Oct 05, 2015 10:44 am

Re: countersheets extension (counters, cards, mail merge from CSV)

Postby Moini » Tue Jan 29, 2019 8:32 am

Btw. the 'insisting' is relative. For third-party extensions, there are no restrictions at all, and for those that go into the main repository, if they are really useful, I think Martin might also take them without the tests.
Something doesn't work? - Keeping an eye on the status bar can save you a lot of time!

Inkscape FAQ - Learning Resources - Website with tutorials (German and English)


Return to “Inkscape Resources”

Who is online

Users browsing this forum: No registered users and 7 guests