Bay 12 Games Forum

Please login or register.

Login with username, password and session length
Advanced search  

Author Topic: MacroGen - Full control macro generation from images (v1.2)  (Read 2887 times)

milo christiansen

  • Bay Watcher
  • Something generic here
    • View Profile
MacroGen - Full control macro generation from images (v1.2)
« on: April 25, 2014, 04:40:28 pm »

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

Download (from DFFD)
« Last Edit: May 08, 2014, 06:08:39 pm by milo christiansen »
Logged
Rubble 8 - The most powerful modding suite in existence!
After all, coke is for furnaces, not for snorting.
You're not true dwarven royalty unless you own the complete 'Signature Collection' baby-bone bedroom set from NOKEAS

rmblr

  • Bay Watcher
    • View Profile
Re: MacroGen - Full control macro generation from images (v1.0)
« Reply #1 on: April 29, 2014, 08:17:49 am »

Cool.. setting up a go dev env on my linux box to test this out.

In the meantime, two things:

  • Its convention to put a toplevel folder in your zip file: MacroGen/<the files>
  • What do you do with the macro files after generating them? Can you use them in DF without restarting?

Edit: also it would be more useful, imho, if this was implemented as a dfhack script (like the current digfort script).
« Last Edit: April 29, 2014, 08:20:50 am by rmblr »
Logged

Meph

  • Bay Watcher
    • View Profile
    • worldbicyclist
Re: MacroGen - Full control macro generation from images (v1.0)
« Reply #2 on: April 30, 2014, 06:48:34 am »

Macros for setting up uniform templates would be amazing. :)
Logged
::: ☼Meph Tileset☼☼Map Tileset☼- 32x graphic sets with TWBT :::
::: ☼MASTERWORK DF☼ - A comprehensive mod pack now on Patreon - 250.000+ downloads and counting :::
::: WorldBicyclist.com - Follow my bike tours around the world - 148 countries visited :::

milo christiansen

  • Bay Watcher
  • Something generic here
    • View Profile
Re: MacroGen - Full control macro generation from images (v1.0)
« Reply #3 on: April 30, 2014, 04:44:52 pm »

Macros for setting up uniform templates would be amazing. :)

But very hard to do, and in any case not what MacroGen was designed for, sorry.

  • Its convention to put a toplevel folder in your zip file: MacroGen/<the files>
  • What do you do with the macro files after generating them? Can you use them in DF without restarting?

Edit: also it would be more useful, imho, if this was implemented as a dfhack script (like the current digfort script).

About #1, that's not necessarily true and it is a practice I really dislike, anyway about half the zips I find are done that way and the other half are done the way I do it, sorry not going to change.
As for #2, put them in your data/init/macro folder, and yes DF can read macros without restarting, but it will only read each one once, so if you change a macro it will not read it again until you restart, adding new ones is not a problem.

Implementing as a DFHack script is out of the question. Do you know how to read images from Lua? Thought not.
I do agree that it would be cool though, maybe someday...

Anyway here is 1.1, it fixes a major bug with raw bindings and adds a new example showing how to designate minecart tracks.
Logged
Rubble 8 - The most powerful modding suite in existence!
After all, coke is for furnaces, not for snorting.
You're not true dwarven royalty unless you own the complete 'Signature Collection' baby-bone bedroom set from NOKEAS

milo christiansen

  • Bay Watcher
  • Something generic here
    • View Profile
Re: MacroGen - Full control macro generation from images (v1.2)
« Reply #4 on: May 08, 2014, 06:11:00 pm »

So 1.2 is up, and barring a strange mood or a bug this is probably one of the last versions.

Basically I exposed far more stuff to scripts and removed a lot of the limiting things like automatic image loading, all in all MacroGen is now far more flexible.
Logged
Rubble 8 - The most powerful modding suite in existence!
After all, coke is for furnaces, not for snorting.
You're not true dwarven royalty unless you own the complete 'Signature Collection' baby-bone bedroom set from NOKEAS