Blah Blah Blah... You don't need to read the following if you aren't in mood of readingHi, i'm kinda new to DF (tried it once a long time ago, and ran away because of interface, not graphics, just the messy menus and no typist friendly keybinds).
Anyways i recently installed it to see the game improvements, and give it a second try, and thanks to the Lazy Newb Pack, i found that cool application that probably many DF players love:
Quick Fortress.
After playing a bit with QF, i ended up using
Chroma Fort too, i liked the idea but i didn't like how was implemented, mapping the colors manually in each run was a pain and even found a bug when i tried to process my first images
...
So I started to make a simple script to do the job, got struck by a strange mood and ended up with a full featured command-line tool to easily batch complete folders in seconds ABOUT IMAGE2QFIt's written in python, the source code and a Windows executable (generated with cx_Freeze) is inside the download.
I pretty much spent more time coding this than playing DF and using QF since my recent DF re-install (i'll play a bit more now it's kinda finished
, i didn't made unittests (my bad) and didn't manually test it too much, so it may contain bugs.
DOWNLOAD LINKimage2qf-v0.1.zipDOCUMENTATION/HELPI spent a lot of time writing this docs and help files, i hope users at least
try to read them once before asking questions, but i won't mind answering them
BTW English isn't my main language (spanish is), so there are probably a few unreadable sections or mistakes
. Don't be shy and correct me if i did.
You can access all this documentation from the commandline, but i'll post it here too...
MAIN DOCUMENTATION========
Image2QF
========
Converts images to blueprints (CSV files) for QuickFortress.
Supported images formats: BMP was the only one tested.
Color<->Feature mapping
-----------------------
It specifies what each color means, by default this mapping is REALLY short
(only black (representing 'do nothing') and white (digging) in dig mode), you
are supposed to extend this with global and per-image configuration files.
TODO: make a decent default list so most players feel confortable with the same
colors
Configuration files
-------------------
You can specify a global configuration file with the --config argument, the
colors<->feature set in this file will completely override default ones. You
can even create specific configuration files for each image (using the same
name but different extension), and this file will override even the global
options set by --config. This per-image files are loaded automatically. As
general rule, specific options override general options.
IMPORTANT: You can create per-image configuration files that gives header
metadata information only (QF mode, blueprint start point, blueprint
description) and doesn't overide global color<->feature set.
Configuration file structure
----------------------------
The configuration files are read as JSON or YAML (based on the extension used,
'.json' or '.yaml')
TODO: document more about the structure. Looking a generated YAML configuration
file should be pretty obvious for those who have an idea of how the QF's CSVs
are defined.
Specifying a QF mode
--------------------
QuickFortress needs to know what menu the blueprint use. All CSV files needs
at least a QF mode, and that info isn't in the image file, there's 2 ways to
specify it (in order, the first found is used):
- with a per-image configuration file (same name as the image)
- adding a suffix in the image filename This suffix is a combination of a
separator (one of "-_. ") and a mode (for example 'bedroom-dig.bmp',
'walls.build.bmp', 'my stockpiles place.bmp').
Recommended usage
-----------------
Just create a batch file or windows shortcut running the 'convert' subcommand
in your blueprints directory and the .csv files will get updated every time you
execute it. There are only a few things you need to configure:
- the colors<->feature mapping, you need to specify what colors mean what (the
best way is using a global configuration file for the majority of your images
(which always use the same colors) AND then create specific configurations
for those images who have different color<->feature mappings.
- the QF mode (explained in 'Specifying a QF mode')
- (optional) if you have at least a mildly OCD (like me :P), you'll probably
want to specify the blueprint description, the starting position of your
blueprint and what does that point represent, of course this information is
used by QF and presented to the user when he loads the CSV, so it's nice to
have, you can specify it with a per-image configuration file.
Examples
--------
image2qf convert documents/myblueprints
Creates CSV files (with same name as the image but .csv extension) for
all supported images in the 'documents/myblueprints' directory.
image2qf --config myblueprints/myconfig.yaml convert myblueprints
Same as before but using a global configuration file, with it you can
specify what to do with each mode-color combination (for example blue in
dig mode represents up/down stairs, while blue in build mode represents
build a wall)
MAIN COMMAND HELP (image2qf -h)usage: image2qf [-h] [-v] [--debug] [--config CONFIG]
{test,show-documentation,convert,generate-config} ...
Convert images QuickFortress blueprints (CSV files).
Use it at your own risk. :)
optional arguments:
-h, --help show this help message and exit
-v, --version show program's version number and exit
--debug normal operations and errors are extra verbose
--config CONFIG set CONFIG file as the global configuration file
subcommands:
use 'image2qf {subcomand} -h' for more help
{test,show-documentation,convert,generate-config}
main subcommands
test run unittests, helps development testing
show-documentation show an extensive documentation, read at least once
convert search (recursively) for supported images in specified
directories and creates a csv file (with same
filename) for each one
generate-config generate a configuration template file for each image
in indicated directories (recursively), the new file
will contain all colors of the image and a header
placeholder. The global configuration file and/or a
previous per-image configuration file will serve as a
base for the new one. Newly found colors will be added
to the existing list with a no-op character (backtick:
`)
CONVERT SUBCOMMAND HELP (image2qf convert -h)usage: image2qf convert [-h] directory [directory ...]
positional arguments:
directory list of directories to scan for supported images to convert
optional arguments:
-h, --help show this help message and exit
GENERATE-CONFIG SUBCOMMAND HELP (image2qf generate-config -h)usage: image2qf generate-config [-h] [--format FORMAT] [--suffix SUFFIX]
[--overwrite] [--mode QFMODE] [--header-only]
directory [directory ...]
positional arguments:
directory list of directories to process
optional arguments:
-h, --help show this help message and exit
--format FORMAT format used by the newly generated config files
--suffix SUFFIX suffix used for the new config files
--overwrite overwrite files if already exist
--mode QFMODE QF mode stored in the config file when other finding
methods fail (already existing per-image config or filename
suffix)
--header-only this option force to generate config files with header
information only, useful if always use the same global
config file to map colors to fortress features. used with
--overwrite and no --suffix WILL DELETE FOREVER all your
color definitions from all the processed configuration
files, i warned you.
Happy DF, i'm going back to my fortress at last, those tough little guys must be thirsty by now