Multiwinia

[jelco]

GuideGridTool
v0.2.2 (August 15th 2009)

Downloads

• 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.

Syntax:
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.
Example grid
Example image

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.

Jelco

Last edited by jelco on Sun Aug 16, 2009 1:13 am; edited 2 times in total

[jelco]

0.2.0 is up. Two important new changes:

• The lazy mode (switch -l at the end of the command) saves you the hassle of having to provide data. 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. It can save you a lot of time but is generally not suited for anything but testing purposes.
  
  Example syntax:
  ggt -i2m image.jpg map.txt -l
  
• 
  
• The map-dump feature will scan the supplied map file for landscape tiles with guide grids and save all of them to numerically ordered images named after the original map filename.
  
  Example syntax:
  ggt -md map.txt

Jelco

[jelco]

0.2.1 is up.

• Most importantly, the overlap for image-to-map has been shinified. It is no longer a hack which produces bad-looking results, but it actually accounts for the overlap by making sure the pixels at the edges of meeting tiles match. As a result, the resolutions for input images now adhere to stricter standards. See the README for details.
  
• 
  
• A minor bug has been fixed which made the application crash when entering an invalid value for the ratio

Jelco

[jelco]

Immediately followed by 0.2.2.

• The image-to-map feature now also compensates for the odd behaviour Xwinia exhibits when the maximum pixel height in a guide grid is not the maximum possible value. It corrects tile heights and leaves out tiles entirely if they turn out to be empty (something which was neglected previously and could create weird results if certain areas of an image were completely black). This is just an under-the-hood change and doesn't require you to do anything differently when using the tool, but it will reduce (hopefully eradicate completely) unexpected results to do with this Xwinia behaviour.

Jelco