v0.2.2 (August 15th 2009)
- Latest public version, Python source + Win32 executable: 0.2.2
Alright, so because I offered to do this on a whim and then was slightly pressurized into actually doing it by TGF here's a small Python script that can convert guide grids to image files and vice versa.
First things first: this tool was created for use during the Multiwinia beta so it's been in development for a short while now (let's not exaggerate, 2 weeks) and I figured it might be useful to Multiwinia modders - hence this post is basically a copy-and-paste job from the original topic. My main working version includes some minor functionality only applicable to the beta so I've had to remove certain parts from this post, hence it might come across as slightly sloppy or incomplete. If something is unclear, don't hesitate to ask.
There's a Win32 executable available so that you can run it out of the box but hardcore users (or non-Windows users) might want to go all the way. To run this script you'll first need to have Python installed (2.6, not 3.0), after which you need to get the Python Image Library. After that you can simply invoke ggt.py on the command line and you're set.
ggt.py/ggt.exe --grid-to-image grid.txt image.jpg
ggt.py/ggt.exe --image-to-grid image.jpg grid.txt
ggt.py/ggt.exe --image-to-map image.jpg map.txt
ggt.py/ggt.exe --map-dump map.txt
All commands have shortened versions (-g2i, -i2g, -i2m and -md respectively) and you can find some help when running the app without arguments. Needless to say, it's a command-line app.
Currently the grid file has very strict requirements because I didn't feel like coding in flexibility at this hour (yay almost 4AM and a diploma ceremony 'tomorrow' night). It must be exactly the guide grid you want - it can't even have a newline at the end.
There's two example files you can download. These files are each other's counterparts so converting between them should be an easy tryout. It's a center guide grid from one of my own Multiwinia maps, one with steady slopes to four sides.
Colours in images, very simple: White is high, black is low. If you convert a colour image to a guide grid it will take the average value of red, blue and green for each pixel to calculate the value it wants - this means that a 100% red, blue or green pixel is equal to a 33% black pixel and 100% cyan, magenta or yellow is equal to 66% black. This might come across as confusing, and if it is, just don't try it.
As for image files it'll understand, that depends entirely on the PIL. It supports PNG, JPEG and BMP as far as I'm aware and since those are the most common formats I guess that'll do. I don't know about image sizes that create unworkable guide grids for MW, but the highest res guide grids equal a 31x31 image, so stick to that if you want to play it safe. If you want to experiment, do try it and do tell me the results - note that it must always be a square however. For some reason PNGs don't seem to work out perfectly - full white works out as roughly 50% in the resulting grids - so sticking to BMPs and JPEGs is the best way to go. When using JPEGs, make sure to keep the quality level at 100, because otherwise you'll have compression artefacts messing up your grids.
The core feature of the app is --image-to-map/-i2m, which can split up an image into multiple smaller images to fit with guide grid resolutions (you are restricted to certain resolutions nonetheless, see README). When using this it will ask you for a size ratio (controls the size of the landscape tiles, experiment to find out what works best for you - I prefer something between 20 and 30), a maxheight value, and offsets for x, z and y (note that due to Chris' weird naming convention, y is the vertical dimension and x and z horizontal, hence they're asked in that order). If the output file you supplied is a pre-existing txt file it will try to handle it as a map file and ask you if you want to overwrite the file or append the grids to the map. Note that landscape tiles are not truncated when appending to a map so if you want to try multiple times to e.g. experiment with the ratio, use backup files.
The overlap between multiple tiles when using -i2m is not very clean yet, but for the moment it does the job. I'm going to have to look into a slightly more professional solution later on (currently the tiles just overlap 10%).
Even when using an image that is just for one tile and it doesn't need to be cut up into multiple tiles, use -i2m because it includes formatting and saves you a lot of hassle with the offsets and height/size definitions. The other two commands are generally 'raw' commands, although formatting with a default set of values is possible for the -i2g feature ("ggt -i2g image.jpg grid.txt -f" gives you offsets of 0 and a maxheight of 200). On top of this, -i2m is the only command that currently does and will ever support writing into pre-existing map files.
There is a lazy mode for the image-to-map feature which will save you a lot of hassle. It is mainly intended for testing purposes. It will enter default ratio, height and offset values, will automatically try to append if the file pre-exists and falls back to overwriting if this fails. The default ratio is 20, the default maxheight is 200, and the default offsets are 0.
The map-dump feature will scan the supplied map file for any landscape tiles with guide grid definitions and will save them in separate JPEG files named after the original map filename and numbered in the order in which they appear in the map file. It doesn't include any offset, height or size values, just the guide grids.