Script to make common operations on piece images

[cholmcc]

Counter image manipulations

The script piece_manip.sh (Right-click and select Save link as …) allows for a number of manipulations of counter images. The syntax is in general

./piece_manip.sh [OPTIONS] INPUT ... 

where OPTIONS specify which operations to do, and INPUT ... is a number of input files. Try also

./piece_manip.sh --long-help 

for information on operations. If no output file is specified via option -o or --output, then for input file INPUT.EXT, the default output file name is INPUT_out.png.

The script uses ImageMagick, and is inspired by grouchysmurf’s, now defunct, web-page vassal.neocities.org (Wayback machine). Credit to that user for finding various useful operations.

This script is not meant to be omnipotent. Many more possible and sensible operations could be defined, and much more fancy stuff can be done with ImageMagick. Please refer to the document of ImageMagick, not least the extensive list of examples.

Overview

Original	--bevel	--border	--color	--crop	--drop	--expand	--outline	--rounded	--shade	--shave	Combined

Some common notes

Colours

Any colour that Imagemagicks knows about can be used, or alternatively the colour can be given using HTML colour codes (#RRGGBB, where RR, GG, BB, are hexadecimal numbers between 0x00 and 0xFF, and corresponds to the red, green, and blue channels, respectively).

Sizes

Sizes are always given in image pixels.

Copyright

Typically, the publisher of the game holds the copyright on the materials of the game. While copyright can most likely not be claimed over game mechanics and design, it can be enforced on artistic and original work. Graphics, such as counters, maps, cards, etc. definitely fall in that category.

Thus, if you modify or redistribute such materials - counters, maps, cards, etc. - you should make sure that the copyright holders have given you license to do so, and you should explicitly provide that license. Otherwise, you are most likely liable for copyright infringement.

Crop images from counter sheet

./piece_manip.sh --extract N M [FLIP] INPUT ...

where INPUT is N columns and M rows of pieces. If FLIP is true, yes, 1, flip, flop, or back, then the order of pieces are reversed. This is useful when extracting images from the “back” counter sheet so as to reproduce the order of the images used on the front sheet.

Output file names are

INPUT_NUM.png

where NUM is a serial number, starting at zero, zero-padded to 3 digits - e.g., if the input file name is front_block.png, then the 6th extracted image will be named front_block_005.png.

Examples

./piece_manip.sh --extract 9 2 front_block.png 
./piece_manip.sh --extract 9 2 1 back_block.png 

Input:

Given the counter sheets

Front	Back

cut out the individual blocks, using for example Gimp, as shown below

front_block.png
back_block.png

Output:

Bevel

./piece_manip.sh --bevel [SIZE] INPUT ...

Add a bevel (“button” effect) of size SIZE pixel to images. If SIZE is not specified it defaults to 4

Example

./piece_manip.sh --bevel 4 counter1.png -o counter1_bevel.png
./piece_manip.sh --bevel 4 counter2.png -o counter2_bevel.png

Input	Output

Border

./piece_manip.sh --border [SIZE [COLOUR]] INPUT ...

Add a COLOUR-coloured border of size SIZE pixel to images. If SIZE is not specified it defaults to 4. If COLOUR is not specified, it defaults to black.

Example

./piece_manip.sh --border 1 red counter1.png -o counter1_border.png
./piece_manip.sh --border 1 red counter2.png -o counter2_border.png

Input	Output

Color

./piece_manip.sh --color [N [DITHER]] INPUT ...

Reduce the number of colours used by the image to N (defaults to 16). If DITHER is no, false, no-dither, 0, or off, then dithering is turned off (default is on). The purpose of this operation is to reduce the image size. For many images, the size can be reduced to about 25% of the original size.

Example

./piece_manip.sh --color 5 5 -o counter1_color.png
./piece_manip.sh --color 5 5 -o counter2_color.png

Input	Size	Output	Size
	17.8kb		3.9kb
	20.6kb		4.2kb

Crop

./piece_manip.sh --crop GEOM INPUT ...

Crop piece to geometry GEOM. GEOM has the format

WIDTHxHEIGHT[+/-X+/-Y]

where WIDTH and HEIGHT are the new width and height, respectively, and X and Y are the horizontal and vertical offsets, respectively, with respect to the centre of the image.

Example

./piece_manip.sh --crop 100x100 -o counter1_crop.png
./piece_manip.sh --crop 100x100 -o counter2_crop.png

Input	Output

Drop

./piece_manip.sh --drop [SIZE [COLOUR [FADE [OPACITY]]]] INPUT ...

Add a COLOUR-coloured drop-shadow to images. If COLOUR is not specified, it defaults to gray7. If FADE is positive, then the shadow will fade of that many pixels. OPACITY sets the opacity of the start of the drop-shadow. SIZE defaults to 4, FADE to 0, and OPACITY to 60.

Example

./piece_manip.sh --drop 2 "#11111e" 4 counter1.png -o counter1_drop.png
./piece_manip.sh --drop 2 "#11111e" 4 counter2.png -o counter2_drop.png

Input	Output

Expand

./piece_manip.sh --expand SIZE INPUT ...

Add a SIZE pixels to the top and bottom of the images. The colours of these extra pixels are sampled from the edge of the image. In some sense, this is the reverse of --shave.

Example

./piece_manip.sh --expand 2 counter1.png -o counter1_expand.png
./piece_manip.sh --expand 2 counter2.png -o counter2_expand.png

Input	Output

Outline

./piece_manip.sh --outline [COLOUR] INPUT ...

Add a COLOUR-coloured outline to images. If COLOUR is not specified, it defaults to black.

Example

./piece_manip.sh --outline blue counter1.png -o counter1_outline.png
./piece_manip.sh --outline blue counter2.png -o counter2_outline.png

Input	Output

Rounded

./piece_manip.sh --rounded [SIZE] INPUT ...

Make the corners of the images rounded. The radius is set by SIZE. SIZE defaults to 16.

Example

./piece_manip.sh --rounded 16 -o counter1_rounded.png
./piece_manip.sh --rounded 16 -o counter2_rounded.png

Input	Output

Shade

./piece_manip.sh --shade [SIZE [ANGLE [ELEVATION]]] INPUT ...

Add a smooth bevel to the image of size SIZE. The shade is drawn as if the light-source is at the angle ANGLE and elevation ELEVATION (both in degrees, and defaults to 135 and 30, respectively). Note that ANGLE is in the range 0 to 360 and ELEVATION in the range 0 to 90, though the extremes should be avoided.

Example

./piece_manip.sh --shade 5 -o counter1_shade.png
./piece_manip.sh --shade 5 -o counter2_shade.png

Input	Output

Shave

./piece_manip.sh --shave X Y INPUT ...

Shave off from left and right, top and bottom of the image. X is the number of pixels to remove both from the left and right edges, while Y is the number of pixels to remove from the top and bottom edges.

Example

./piece_manip.sh --shave 5 5 -o counter1_shave.png
./piece_manip.sh --shave 5 5 -o counter2_shave.png

Input	Output

Combining manipulations

The above manipulations can be combined. That is, one can specify multiple operations for a single image file. The will then be applied in the order given. Note that the order matters.

Example

./piece_manip.sh         \
    --bevel 8            \
	--rounded 16 	     \
	--outline black	     \
	--drop 2 "#11111e" 4 \
    --color 16           \
	-o counter1_fancy.png counter1.png
./piece_manip.sh         \
    --bevel 8            \
	--rounded 16 	     \
	--outline black	     \
	--drop 2 "#11111e" 4 \
    --color 16           \
	-o counter2_fancy.png counter2.png

Input	Output

Note, the option --color 16 reduces the final image size to just over 25% if that option had not been specified, and a roughly 40% of the original image. If instead --color 32 had been specified, then the final size would be roughly 50% or the original image size.

License

The script piece_manip.sh is licensed under the GNU General Public License version 3, or later. See also LICENSE.

[Reg]

Hi Christian,

Thank you for such a comprehensive and well thought out utility. The comprehensive documentation is a great feature.

My only observation is that the use of the ‘magick’ command in the script requires the installation of ImageMagick V7. Unfortunately Ubuntu and other Debian based distributions only have V6 in their repositories.

I am aware the accepted solution is to download the source and compile a V7 installation (which would be a worth while exercise) but it might be a bit daunting for a new user.

Would it be worth considering a ImageMagick V6 version of this script (as not all the features are used) or possibly an auto detect version which it would work ‘out of the box’ for these distributions?

(Possibly just as simple as conditional substitution of ‘convert’ for ‘magick’).

Just a thought,
Reg.

[cholmcc]

@Reg

Thank you for such a comprehensive and well thought out utility. The comprehensive documentation is a great feature.

Glad you find it useful.

@Reg

My only observation is that the use of the ‘magick’ command in the script requires the installation of ImageMagick V7. Unfortunately Ubuntu and other Debian based distributions only have V6 in their repositories.

I’m on Debian GNU/Linux “sid” - and has been since 1996 - and there magick is available

@Reg

I am aware the accepted solution is to download the source and compile a V7 installation (which would be a worth while exercise) but it might be a bit daunting for a new user.

Since imagemagick does not have that many dependencies, you may also be able to install the sid (unstable) package (most dependencies comes from libmagickcore-7).

@Reg

Would it be worth considering a ImageMagick V6 version of this script (as not all the features are used) or possibly an auto detect version which it would work ‘out of the box’ for these distributions?

It would be great to have the piece_manip.sh script be compatible with ImageMagick 6. However, I’m not that familiar with the tool to know exactly what the differences are between v6 and 7. So …

@Reg

(Possibly just as simple as conditional substitution of ‘convert’ for ‘magick’).

… if you could give that a try, that would be great. You can check out the script by

$ git clone https://gitlab.com/wargames_tex/vassal_my_contrib.git

The script lives in the imagemagick sub-directory. You will only need to change magick to convert in line 610. You can then do

$ make clean 
$ make 

in that directory to test your changes. Please report back your findings. Thanks.

Yours,
Christian

[/quote]

[Reg]

Hi Christian,

Substituting the convert command into the script works just fine for ImageMagick V6 with the single exception of the --rounded operation which throws an error of:
convert-im6.q16: invalid argument for option `-size': %[fx:w]x%[fx:h] @ error/convert.c/ConvertImageCommand/2763.

I didn’t think there would be a great difference between the versions but obviously there are some subtleties. When I get some time tonight I’ll see if I can get that to work.

As far as the repositories go I think the issue is with the Ubuntu repositiory which only contains V6. I am using ZorinOS which is buillt over the top of a Ubuntu baseline. I believe the Mint distribution is similar. Installing a ImageMagick V7 on these distributions is not difficult and well documented but I thought it would be desirable for this utility just to work ‘out of the box’ for as many users as possible.

By the way, have you implemented the --expand operation shown above? It doesn’t appear to be in the script.

Thank you again for your great contributions,
Reg

[cholmcc]

Hi Reg,

@Reg

Substituting the convert command into the script works just fine for ImageMagick V6 with the single exception of the --rounded operation which throws an error of:
convert-im6.q16: invalid argument for option -size’: %[fx:w]x%[fx:h] @ error/convert.c/ConvertImageCommand/2763.`

Yep, I saw that too with convert from ImageMagick 7 - so consistent across versions - so far so good.

The big change seems to be that v7 allows you to put expression in arguments to the various ImageMagick operations - e.g.,

-size %[fx:w]x%[fx:h] 

which v6 (or v7 convert) does not allow for.

I’ve made a work-around in the script for the pesky --rounded operation. A bit of a hack (see the script for some thoughts on this).

@Reg

…
but I thought it would be desirable for this utility just to work ‘out of the box’ for as many users as possible.

For people that are not hype about rebuilding software, I though it might be worth trying the sid packages. That’s all. I guess we’re not all on the edge (if you can call sid “the edge” - after all its more stable than RH has ever been - going crazy is Gentoo or Debian “experimental” - still, beats Windoze and MacOuze. Oh, and in case people are wondering why “unstable” is called “sid”).

@Reg

By the way, have you implemented the --expand operation shown above? It doesn’t appear to be in the script.

It should have been there - did you re-download the script? I cannot push stuff on to your machine (or … can I? ) Anyways, the fix above have been pushed, and so the --expand option should definitely be there now - just re-download using the link at the top of the top post.

Yours,
Christian