Skip to main content

Hartwork Blog

Free Software, Music, Chinese Chess

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 PlayOK.com, 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
GAME    
RED             ;;;
BLACK           ;;;
DATE            2014-07-16
FEN             4kaer1/4a2c1/2h1e1h2/3Rp1C1p/2C6/5rP2/1pP1P3P/8E/9/1cEAKA1R1 b

START{
}END

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:
  INPUT_FILE
  OUTPUT_FILE

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
  --debug

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

# find themes -maxdepth 2 -type d | sort
themes
themes/board
themes/board/a4_blank_2cm_margin
themes/board/clean_alpha
themes/board/clean_beta
themes/board/commons_xiangqi_board_2008
themes/board/commons_xiangqi_board_2008_bw_thin
themes/board/dhtmlxq_2014_remake
themes/board/latex_xq_remake
themes/board/minimal
themes/board/minimal_chinese
themes/board/minimal_chinese_arabic
themes/board/playok_2014_remake
themes/board/xiexie_2_5_0_remake_minimal
themes/pieces
themes/pieces/ccbridge_3_0_beta4_default_preview_remake
themes/pieces/commons_xiangqi_pieces_print_2010
themes/pieces/commons_xiangqi_pieces_print_2010_bw_heavy
themes/pieces/latex_xqlarge_2006_chinese_autotrace
themes/pieces/latex_xqlarge_2006_chinese_potrace
themes/pieces/playok_2014_chinese
themes/pieces/playok_2014_chinese_noshadow
themes/pieces/retro_simple

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:
  SVG_FILE
  INI_FILE

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!