MacroGen - Full control macro generation from images

============================================
Overview
============================================

MacroGen is a simple command line utility for generating DF macros from images.

Unlike utilitys like Quick Fort and DF Designator, MacroGen only generates macros from images and only from the command line, no fancy GUI, no ugly and hard to use CSV files, and no buggy attempts to interact with the DF window.

The macros generated by MacroGen use a relatively simple line by line top to bottom left to right output pattern, no attempt is made to find and designate large regions in one go, but runs in the same row are joined (if possible). Column runs on the other hand are impossible to join due to the possibility of having raw bindings, if the raw binding did something unexpected (like moving the cursor and not moving it back, a legitimate, powerful, and slightly dangerous, action) the macro could "go nuts", eg generate wildly incorrect output.

It may seem that this output pattern would make the macros slow to run, but in practice the fact that MacroGen focuses on macro instructions rather than key presses means that the macros run at about the same speed as the output from qfconvert for the same pattern (even though there are more actions overall, there are far fewer instructions).

Of course you need to know the macro instructions for the action you want to accomplish, but the included examples have the most common ones for dig type designations (which is the use for which MacroGen was designed).

In theory it should be possible to use MacroGen to generate macros for every application that can be expressed naturally by a one pixel per tile image (and even some that cannot).

The only supported image format is PNG, I could support others without too much trouble, but anything but PNG, GIF and JPEG would require extra effort. GIF isn't really suitable, and I can just imagine the bug reports about failed generation if I allowed JPEG, after all colors need to match exactly to trigger an action...
(So you buy a camera that has a high resolution sensor, and then you save your images using lossy compression, the logic of that (or lack thereof) defies description)

============================================
Usage
============================================

First you need a spec script and a set of blueprint images.

The spec script is a simple Rex script that binds color values to macro actions and defines what images are loaded and where and when they are designated, see the .rex files in the examples for more details.

The blueprint image(s) are a set of one or more PNG images that are named the same as their associated spec script with a ID appended. IDs can be anything you want, for example the image with ID "Test" for file set "Example" would be named "Example Test.png".

To generate the macro from a file set you would run 'macrogen "file set name"', for example 'macrogen Example'. The generated macro is named the same as the spec script with the .mak extension, for example "Example.mak"

============================================
Examples
============================================

There are a few examples in the "Examples" directory, feel free to try them out (and read their scripts for help, they have lots of helpful comments).

"Test" is a simple test pattern, it's spec script has most of the documentation for writing a spec script as comments.

"Awesome Entry" is my favorite fortress entrance and peripherals, an excellent example of a larger blueprint, it's spec script has comments describing it's features in some detail. (This example has a relatively complicated spec script) Also included is a annotated XCF image that details all the features of this entry and how to build them (more detailed then the spec script comments).

"Spiral Wagon Ramp" a three wide spiral wagon ramp, basically the ramp from "Awesome Entry", use for extending the entry ramp if you like to build deep (like I do) and/or for adding the cavern exit.

"Tracks" designates a simple circle of minecart tracks, a demo for raw bindings.

============================================
Error Reporting
============================================

Error handling is nonexistent, any error will make MacroGen exit and print a stack trace (if you are going to report a bug this information is invaluable). MacroGen will never make any changes to any files other than the macro file, so even if it does crash it won't hurt anything.

Please do not complain about errors obviously caused by bad input, for example if MacroGen complains about an image not being found it is generally the users fault, check your spec script.

If you have a generated macro that "goes nuts" (when it shouldn't) or MacroGen generates incorrect output of any kind, please send me the file set that caused it, as that will help immeasurably with the bug squashing.

============================================
Change Log
============================================

v1.2
Changed the internals significantly, MacroGen is now a thin wrapper around a small number of powerful Rex script commands, this makes MacroGen FAR more flexible than it was at the expense of slightly more complicated spec scripts.

Most of the old script commands are gone, replaced with new more powerful ones.

All the standard Rex script commands are now loaded. It should now be possible to abuse MacroGen into doing just about anything, be careful.
Be aware that Rex is still in a state of flux, and likely will stay that way until it is frozen for the Rubble 4.0 release. Commands (and possibly even base syntax) may change and/or be removed without warning! This "issue" won't effect this version but may cause problems in the future.

The Rex command docs are now included (in the "Other/Rex Docs" directory).

32 bit X86 Linux and OSX binaries are now included (in the "Other/linux_386" and "Other/darwin_386" directories).

Added an annotated XCF image to the "Awesome Entry" example, this should make it much easier to figure out what everything is.

Added example "Spiral Wagon Ramp", a rather simple multi-layer blueprint.

v1.1
Removed support for the .bmp extension, the image loader I use can't load bitmaps by default (I thought it could) and I am too lazy to roll my own loader plugin...

Added an example for designating minecart tracks, "Tracks".

And with the new example it became obvious that the cursor would not be moved to the correct starting location before a raw binding was inserted, fixed.

Added new script command: macro:dir_down, allow changing the designation z-order (sheet 0 is alway the top z-level, but this changes whether it is designated first (the default) or last).

v1.0
First version.