Bay 12 Games Forum

Please login or register.

Login with username, password and session length
Advanced search  

Author Topic: image2qf v0.1 - batch convert images to CSV for QuickFortress  (Read 2810 times)


  • Bay Watcher
    • View Profile

Blah Blah Blah... You don't need to read the following if you aren't in mood of reading
Hi, 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 :P and ended up with a full featured command-line tool to easily batch complete folders in seconds :)

It'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.


I 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 :P. 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...

Code: [Select]
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

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',
  '', '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.

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)
Code: [Select]
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

  use 'image2qf {subcomand} -h' for more help

                        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)
Code: [Select]
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)
Code: [Select]
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
  --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 :)
« Last Edit: September 24, 2016, 08:59:34 pm by KurzedMetal »
Quote from: ARandomGuyOnTheInternet
When 80% of your fans use 3 different external programs simultaneously to play your game comfortably, you might need to stand back and think "Maybe...Maybe I should get around making a UI designed to be used by carbon-based entities, like mammals".


  • Bay Watcher
  • The cake is a lie
    • View Profile
Re: image2qf v0.1 - batch convert images to CSV for QuickFortress
« Reply #1 on: June 14, 2011, 07:55:24 pm »

This sounds amazing, will have to try it, thanks!


  • Escaped Lunatic
    • View Profile
Re: image2qf v0.1 - batch convert images to CSV for QuickFortress
« Reply #2 on: June 12, 2013, 01:25:04 pm »

I'd love to use this tool, but it is unclear how the configuration file (yaml or json) works. Also, no tests directory is included in the zip file, so the tests fail.