Skip to main content

Generating Xiangqi setup images, publishing/print level quality

(Last edit 2014-08-31) I wrote a tool that takes the board setup from a WXF file (example below) and produces an SVG image visualizing that setup. Different themes for board and pieces are supported (including your own), the gap between pieces can be adjusted, output width can be adjusted, too. It's called xiangqi-setup. Internally, the tool takes the an SVG file of the board, places piece SVGs at the right places and saves the result. The tool uses svgutils by Bartosz Telenczu. I'm very happy he made that available as free software. My tool is free software (licensed under GNU AGPL 3.0 or later) too, of course. If you want to imitate the style of Chinese end- game books, you could go with these themes:

(Image licensed under CC0 1.0 Universal: Public Domain Dedication)

If you want to imitate LaTeX xq 0.3 style (with added flexibility), you could go with this:

(Image licensed under CC0 1.0 Universal: Public Domain Dedication)

If you would rather go for something more colourful, for screen rather than print, or you want to explicitly imitate the look of, you could go with this:

(Image licensed under CC0 1.0 Universal: Public Domain Dedication, piece artwork kindly shared and released by PlayOK)

There is a version of the pieces without shadows (for PDF generation), too. Latter image was created running

# ./xiangqi-setup \
    --board themes/board/playok_2014_remake/ \
    --pieces themes/pieces/playok_2014_chinese \
    --scale-pieces 1.025 \
    --width-px 400 \
    demo.wxf setup_imitate_playok.svg

This what you pass in: a WXF file (e.g. produced by XieXie by saving with .wxf extension):

FORMAT          WXF
RED             ;;;
BLACK           ;;;
DATE            2014-07-16
FEN             4kaer1/4a2c1/2h1e1h2/3Rp1C1p/2C6/5rP2/1pP1P3P/8E/9/1cEAKA1R1 b


As of now, the complete usage of xiangqi-setup is:

# ./xiangqi-setup --help
usage: xiangqi-setup [-h] [--board DIRECTORY] [--pieces DIRECTORY]
                     [--width-px PIXEL] [--width-cm CENTIMETER] [--dpi FLOAT]
                     [--scale-pieces FACTOR] [--debug]
                     INPUT_FILE OUTPUT_FILE

positional arguments:

optional arguments:
  -h, --help            show this help message and exit
  --board DIRECTORY
  --pieces DIRECTORY
  --width-px PIXEL
  --width-cm CENTIMETER
  --dpi FLOAT
  --scale-pieces FACTOR

For themes, these are your options (at the moment):

# find themes -maxdepth 2 -type d | sort

If none of the existing themes fit your needs, you may create board and/or pieces of your own. For boards, drawing a custom grid, palace, start markers and border can be done using the xiangqi-board tool. A demonstration of its current options:

# ./xiangqi-board --help
usage: xiangqi-board [-h] [--line-thickness-px FLOAT] [--field-width-px FLOAT]
                     [--field-height-px FLOAT] [--border-thickness-px FLOAT]
                     [--border-gap-width-px FLOAT]
                     [--border-gap-height-px FLOAT] [--cross-width-px FLOAT]
                     [--cross-thickness-px FLOAT] [--cross-gap-px FLOAT]
                     SVG_FILE INI_FILE

positional arguments:

optional arguments:
  -h, --help            show this help message and exit
  --line-thickness-px FLOAT
                        Line thickness of square fields in pixel (default: 1)
  --field-width-px FLOAT
                        Width of fields in pixel (default: 53)
  --field-height-px FLOAT
                        Height of fields in pixel (default: 53)
  --border-thickness-px FLOAT
                        Line thickness of border in pixel (default: 2)
  --border-gap-width-px FLOAT
                        Widtn of gap to border in pixel (default: 40)
  --border-gap-height-px FLOAT
                        Height of gap to border in pixel (default: 40)
  --cross-width-px FLOAT
                        Width of starting position cross segments in pixel
                        (default: 10)
  --cross-thickness-px FLOAT
                        Line thickness of starting position cross in pixel
                        (default: 1)
  --cross-gap-px FLOAT  Gap to starting position cross in pixel (default: 4)

For text on the river, the characters are:

  • Chu river: 楚河
  • Han border: 漢界 traditional, 汉界 simplified

On the Open Source font end of things these are your main options to my understanding:

On a side note, in Gentoo Linux look for these packages:

  • Adobe Source Han Sans: media-fonts/source-han-sans (gentoo-zh overlay)
  • AR PL UKai/UMing CN/TW: media-fonts/arphicfonts
  • Google Noto Sans CJK: media-fonts/notofonts (betagarden overlay)
  • Wangfonts: media-fonts/wangfonts (gentoo-zh overlay)
  • WenQuanYi Micro/Zen Hei: media-fonts/wqy-microhei, media-fonts/wqy-zenhei

If you use xiangqi-setup tool to generate images, feel free to drop me a mail, I would be curious to see your results and check out your custom themes. I would not mind a free of copy of your book, either :) Cheers!