{"id":13459027,"url":"https://github.com/hartwork/xiangqi-setup","last_synced_at":"2025-08-09T22:11:51.798Z","repository":{"id":19318155,"uuid":"22556319","full_name":"hartwork/xiangqi-setup","owner":"hartwork","description":":game_die: Generate razor-sharp Xiangqi (Chinese chess) setup graphics; command line tool + themes","archived":false,"fork":false,"pushed_at":"2025-08-08T16:35:54.000Z","size":1701,"stargazers_count":31,"open_issues_count":0,"forks_count":8,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-08-08T18:25:00.381Z","etag":null,"topics":["boardgames","chinese-chess","command-line-tool","graphics","print","python","python3","scalable-vector-graphics","svg","wxf","xiangqi","xiangqi-setup"],"latest_commit_sha":null,"homepage":"https://blog.hartwork.org/?p=2380","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hartwork.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2014-08-02T19:59:56.000Z","updated_at":"2025-08-08T16:35:58.000Z","dependencies_parsed_at":"2023-12-22T17:24:01.449Z","dependency_job_id":"b81ae4cb-eec2-4b70-8191-bbb4743c90ac","html_url":"https://github.com/hartwork/xiangqi-setup","commit_stats":{"total_commits":305,"total_committers":3,"mean_commits":"101.66666666666667","dds":0.1442622950819672,"last_synced_commit":"e9c0fca3fb7ec4d01562f1ad0c5b5a8b0eeb5950"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/hartwork/xiangqi-setup","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hartwork%2Fxiangqi-setup","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hartwork%2Fxiangqi-setup/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hartwork%2Fxiangqi-setup/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hartwork%2Fxiangqi-setup/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hartwork","download_url":"https://codeload.github.com/hartwork/xiangqi-setup/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hartwork%2Fxiangqi-setup/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269645788,"owners_count":24452806,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-09T02:00:10.424Z","response_time":111,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["boardgames","chinese-chess","command-line-tool","graphics","print","python","python3","scalable-vector-graphics","svg","wxf","xiangqi","xiangqi-setup"],"created_at":"2024-07-31T09:01:01.099Z","updated_at":"2025-08-09T22:11:51.751Z","avatar_url":"https://github.com/hartwork.png","language":"Python","funding_links":[],"categories":["Other useful tools"],"sub_categories":["Games collections"],"readme":"[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)\n[![Build and smoke test](https://github.com/hartwork/xiangqi-setup/actions/workflows/smoke_test.yml/badge.svg)](https://github.com/hartwork/xiangqi-setup/actions/workflows/smoke_test.yml)\n\n\n# xiangqi-setup (and xiangqi-board)\n\n## Overview\n\n**xiangqi-setup** is a command line tool using [svgutils](https://pypi.org/project/svgutils/) 0.3.4 to\nrender [Xiangqi](https://en.wikipedia.org/wiki/Xiangqi) (Chinese chess) board setups from WXF/FEN/[annoFEN](https://github.com/hartwork/xiangqi-setup/blob/master/doc/file_formats.md#annofen)/[XAY](https://github.com/hartwork/xiangqi-setup/blob/master/doc/file_formats.md#xay) files to SVG images.\nWith WXF files that contain move history, **xiangqi-setup** can replay these moves on top of the initial setup —\nall of them, none, or any custom number of moves (using the `--moves COUNT` argument).\nWith [XAY](https://github.com/hartwork/xiangqi-setup/blob/master/doc/file_formats.md#xay)/[annoFEN](https://github.com/hartwork/xiangqi-setup/blob/master/doc/file_formats.md#annofen) files\nit can also draw [arrows](https://github.com/hartwork/xiangqi-setup/blob/master/doc/file_formats.md#arrows), mark a field as \"good\", \"bad\" or involved in a move —\nit can add [annotations](https://github.com/hartwork/xiangqi-setup/blob/master/doc/file_formats.md#annotations).\n\nThe most simple way to render a given setup is:\n\n```console\n# xiangqi-setup input.wxf output.svg\n```\n\nFor file [doc/demo.wxf](https://github.com/hartwork/xiangqi-setup/blob/master/doc/demo.wxf), the result is:\n\n[![](https://raw.githubusercontent.com/hartwork/xiangqi-setup/master/doc/demo_retro_simple.png \"demo_retro_simple.{png,svg}, CC0 1.0 Universal: Public Domain Dedication\")](https://github.com/hartwork/xiangqi-setup/blob/master/doc/demo_retro_simple.svg)\n[![](https://raw.githubusercontent.com/hartwork/xiangqi-setup/master/doc/demo_euro_xiangqi_js.png \"demo_euro_xiangqi_js.{png,svg}, Creative Commons Attribution 4.0: Jasmin Scharrer, Sebastian Pipping\")](https://github.com/hartwork/xiangqi-setup/blob/master/doc/demo_euro_xiangqi_js.svg)\n\n(left: default board, default pieces — right: default board, `euro_xiangqi_js` pieces)\n\nThere are a number of themes to pick from for board and pieces (independently).\nThe `--help` listing below also includes the list of all themes\nand their license information.\n\nThe [default board theme `clean_alpha`](https://github.com/hartwork/xiangqi-setup/blob/master/xiangqi_setup/themes/board/clean_alpha/board.svg)\nhas been generated with command line tool `xiangqi-board`\nthat is included with the **xiangqi-setup** package.  It can be used to create\nvariations of the detault theme, e.g. to create a version with reduced spacing\nin crosses you would run:\n\n```console\n# xiangqi-board --cross-gap-px 2 board.{svg,ini}\n```\n\n\n# Installation\n\nYou can install the latest release using pip like so:\n\n```console\n# pip install xiangqi-setup\n```\n\nIf you would rather run the latest pre-release code off Git `master` in a virtualenv, you could do:\n\n```console\n# git clone --depth 1 https://github.com/hartwork/xiangqi-setup\n# cd xiangqi-setup/\n# python3 -m venv venv\n# source venv/bin/activate\n# pip install -e .\n```\n\n\n# Writing a Book\n\nFor a demo of how to use **xiangqi-setup** in writing a book\nplease see https://github.com/hartwork/xiangqi-book-example .\n\n\n# Usage in Detail\n\n## `xiangqi-setup` — Renders WXF/FEN/annoFEN/XAY Files to SVG Images\n\n```console\n# xiangqi-setup --help\nusage: xiangqi-setup [OPTIONS] INPUT_FILE OUTPUT_FILE\n       xiangqi-setup --help\n       xiangqi-setup --version\n\nGenerate razor-sharp Xiangqi (Chinese chess) setup graphics\n\npositional arguments:\n  INPUT_FILE            location of WXF/FEN/annoFEN/XAY file to render\n  OUTPUT_FILE           location of SVG output file to write\n\noptional arguments:\n  -h, --help            show this help message and exit\n  --debug               enable debugging (e.g. mark corners of the board)\n  --version             show program's version number and exit\n\ntheme selection:\n  --board THEME         name of board theme to use (default: \"clean_alpha\");\n                        please check the list of available themes below\n  --pieces THEME        name of piece theme to use (default: \"retro_simple\");\n                        please check the list of available themes below\n  --annotations THEME   name of annotation theme to use (default:\n                        \"colors_alpha\"); please check the list of available\n                        themes below\n\nscaling:\n  --width-px PIXEL      width of the output in pixels (default: ~248.03, i.e. 7.0cm at 90.0dpi)\n  --width-cm CENTIMETER\n                        width of the output in centimeters (default: 7.0)\n  --dpi FLOAT           resolution of the output in dots per inch (default: 90.0)\n  --scale-pieces FACTOR\n                        factor to scale pieces by (0.0 to 1.2, default: 0.9)\n  --scale-annotations FACTOR\n                        factor to scale annotations by (0.0 to 1.2, default: 0.9)\n\nWXF format arguments:\n  --moves COUNT         how many moves to play (for a file with moves history),\n                        e.g. \"3\" would play the first move of red, the first\n                        move of black and the second move of red and then skip\n                        any remaining moves, \"all\" would play all moves, \"-1\"\n                        all moves but the last, \"-2\" all but the last two\n                        (default: \"0\")\n  --annotate-last-move  Add annotations \"blank_move\" and \"piece_move\" to the\n                        source and target locations of the last move\n\nboard themes (16 available, in alphabetic order):\n  a4_blank_2cm_margin                        (license: CC0-1.0)\n  cambaluc_remake_nolegend                   (license: CC0-1.0)\n  cambaluc_remake_nolegend_nogap             (license: CC0-1.0)\n  ccbridge_3_0_beta4_default_preview_remake  (license: CC0-1.0)\n  clean_alpha                                (license: CC0-1.0)\n  clean_beta                                 (license: CC0-1.0)\n  commons_xiangqi_board_2008                 (license: public-domain)\n  commons_xiangqi_board_2008_bw_thin         (license: public-domain)\n  dhtmlxq_2014_remake                        (license: CC0-1.0)\n  latex_xq_remake                            (license: CC0-1.0)\n  minimal                                    (license: CC0-1.0)\n  minimal_chinese                            (license: CC0-1.0)\n  minimal_chinese_arabic                     (license: CC0-1.0)\n  playok_2014_remake                         (license: CC0-1.0)\n  western_red_wine                           (license: CC0-1.0)\n  xiexie_2_5_0_remake_minimal                (license: CC0-1.0)\n\npiece themes (10 available, in alphabetic order):\n  ccbridge_3_0_beta4_default_preview_remake  (license: CC0-1.0)\n  commons_xiangqi_pieces_print_2010          (license: FDL-1.2+ / CC-BY-SA-4.0)\n  commons_xiangqi_pieces_print_2010_bw_heavy (license: FDL-1.2+ / CC-BY-SA-4.0)\n  euro_xiangqi_js                            (license: CC-BY-4.0)\n  euro_xiangqi_js_tricolor                   (license: CC-BY-4.0)\n  latex_xqlarge_2006_chinese_autotrace       (license: non-commercial)\n  latex_xqlarge_2006_chinese_potrace         (license: non-commercial)\n  playok_2014_chinese                        (license: CC0-1.0)\n  playok_2014_chinese_noshadow               (license: CC0-1.0)\n  retro_simple                               (license: CC0-1.0)\n\nannotation themes (2 available, in alphabetic order):\n  colors_alpha                               (license: CC0-1.0)\n  gray_alpha                                 (license: CC0-1.0)\n```\n\n\n## `xiangqi-board` — Creates Custom Board Themes\n\n```console\n# xiangqi-board --help\nusage: xiangqi-board [-h] [--line-thickness-px FLOAT] [--field-width-px FLOAT]\n                     [--field-height-px FLOAT] [--border-thickness-px FLOAT]\n                     [--border-gap-width-px FLOAT]\n                     [--border-gap-height-px FLOAT] [--cross-width-px FLOAT]\n                     [--cross-thickness-px FLOAT] [--cross-gap-px FLOAT]\n                     SVG_FILE INI_FILE\n\npositional arguments:\n  SVG_FILE\n  INI_FILE\n\noptional arguments:\n  -h, --help            show this help message and exit\n  --line-thickness-px FLOAT\n                        Line thickness of square fields in pixel (default: 1)\n  --field-width-px FLOAT\n                        Width of fields in pixel (default: 53)\n  --field-height-px FLOAT\n                        Height of fields in pixel (default: 53)\n  --border-thickness-px FLOAT\n                        Line thickness of border in pixel (default: 2)\n  --border-gap-width-px FLOAT\n                        Widtn of gap to border in pixel (default: 40)\n  --border-gap-height-px FLOAT\n                        Height of gap to border in pixel (default: 40)\n  --cross-width-px FLOAT\n                        Width of starting position cross segments in pixel\n                        (default: 10)\n  --cross-thickness-px FLOAT\n                        Line thickness of starting position cross in pixel\n                        (default: 1)\n  --cross-gap-px FLOAT  Gap to starting position cross in pixel (default: 4)\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhartwork%2Fxiangqi-setup","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhartwork%2Fxiangqi-setup","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhartwork%2Fxiangqi-setup/lists"}