{"id":20828325,"url":"https://github.com/googlefonts/chws_tool","last_synced_at":"2025-04-15T14:24:00.925Z","repository":{"id":36956791,"uuid":"380306401","full_name":"googlefonts/chws_tool","owner":"googlefonts","description":"Add OpenType chws/vchw features to fonts.","archived":false,"fork":false,"pushed_at":"2025-03-02T11:48:42.000Z","size":677,"stargazers_count":30,"open_issues_count":0,"forks_count":2,"subscribers_count":14,"default_branch":"main","last_synced_at":"2025-04-12T09:47:49.508Z","etag":null,"topics":["cjk","font","opentype"],"latest_commit_sha":null,"homepage":"","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/googlefonts.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2021-06-25T17:11:05.000Z","updated_at":"2025-03-06T14:32:37.000Z","dependencies_parsed_at":"2023-09-23T13:47:13.526Z","dependency_job_id":"081a3787-f7aa-4d15-8adb-6743b0c06acb","html_url":"https://github.com/googlefonts/chws_tool","commit_stats":{"total_commits":98,"total_committers":4,"mean_commits":24.5,"dds":0.4591836734693877,"last_synced_commit":"4a39f54f1f2fcea294738b6bccb043f955b4c64f"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/googlefonts%2Fchws_tool","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/googlefonts%2Fchws_tool/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/googlefonts%2Fchws_tool/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/googlefonts%2Fchws_tool/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/googlefonts","download_url":"https://codeload.github.com/googlefonts/chws_tool/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249086393,"owners_count":21210446,"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","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":["cjk","font","opentype"],"created_at":"2024-11-17T23:14:30.822Z","updated_at":"2025-04-15T14:24:00.901Z","avatar_url":"https://github.com/googlefonts.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Continuous Test + Deploy](https://github.com/googlefonts/chws_tool/actions/workflows/ci.yml/badge.svg)](https://github.com/googlefonts/chws_tool/actions/workflows/ci.yml)\n[![PyPI](https://img.shields.io/pypi/v/chws-tool.svg)](https://pypi.org/project/chws-tool/)\n[![Dependencies](https://badgen.net/github/dependabot/googlefonts/chws_tool)](https://github.com/googlefonts/chws_tool/network/updates)\n\n# chws_tool\n\nThis tool adds the OpenType\n[`chws`], [`vchw`], [`halt`], and [`vhal`]\nfeatures to OpenType/TrueType fonts when any of these features are missing.\nPlease see [east-asian-spacing] for details of these features.\n\nThis tool uses the [east-asian-spacing] package as its core engine,\nand has following advantages:\n* Simpler API and command line options.\n* Supports CJK fonts at [fonts.google.com] in its built-in [config].\n\nTo add new fonts to the supported font list,\nplease see the [Adding Fonts] section below.\n\n[east-asian-spacing]: https://github.com/kojiishi/east_asian_spacing\n[`chws`]: https://docs.microsoft.com/en-us/typography/opentype/spec/features_ae#tag-chws\n[`halt`]: https://docs.microsoft.com/en-us/typography/opentype/spec/features_fj#tag-halt\n[`vchw`]: https://docs.microsoft.com/en-us/typography/opentype/spec/features_uz#tag-vchw\n[`vhal`]: https://docs.microsoft.com/en-us/typography/opentype/spec/features_uz#tag-vhal\n[fonts.google.com]: https://fonts.google.com/\n\n## Install\n\n```sh\npip install chws-tool\n```\nIf you want to clone and install\nin the [editable mode] with the development packages:\n```sh\ngit clone https://github.com/googlefonts/chws_tool.git\ncd chws_tool\npip install -e '.[dev]'\n```\n\n[editable mode]: https://pip.pypa.io/en/stable/cli/pip_install/#install-editable\n\n## Command Line Usage\n\nThe following example adds the features to `input.otf`\nand saves it to the `build` directory.\nIf the argument is a directory,\nthe tool expands it to all fonts in the directory recursively.\n```sh\nadd-chws input.otf\n```\nUse the `-o` option to change the output directory,\nor the `--help` option for the full list of options.\n```sh\nadd-chws input_dir -o output_dir\n```\n\n## API\n\nThe following example creates a font with the features\nin the \"`build`\" directory\nif the features are applicable:\n```python\nimport chws_tool\n\ndef main():\n    output_path = chws_tool.add_chws(\"fonts/input.otf\", \"build\")\n    if output_path:\n        print(f\"Success! saved to {output_path}\")\n    else:\n        print(\"Skipped\")\n```\nIf you prefer to overwrite existing fonts, you can omit the output directory.\n```python\nimport chws_tool\n\ndef main():\n    chws_tool.add_chws(\"fonts/input.otf\")\n```\nIf your program uses [asyncio]:\n```python\nimport asyncio\nimport chws_tool\n\nasync def main_async():\n    output_path = await chws_tool.add_chws_async(\"fonts/input.otf\", \"build\")\n    if output_path:\n        print(f\"Success! saved to {output_path}\")\n    else:\n        print(\"Skipped\")\n\nasyncio.run(main_async())\n```\n\n[asyncio]: https://docs.python.org/3/library/asyncio.html\n\n## Adding Fonts\n[adding fonts]: #adding-fonts\n\nThis package has a built-in list of supported fonts in its [config].\n\nFonts not in the known list are still processed\nwith the default configuration,\nbut this package shows a warning message.\n\nWhen adding new fonts to the known font list,\nthe following process is recommended:\n\n1. Find the font names.\n   Running the `add-chws` with `--print-name` option can print them.\n2. Add them to the [config].\n3. (Optional) Build the font and run the [Visual Test].\n   This step is optional\n   because this package automatically avoids glyph collisions\n   by computing glyph outlines.\n4. (Optional) Tweak the [config] if needed.\n\n[config]: src/chws_tool/config.py\n\n## Visual Test\n[Visual Test]: #visual-test\n\nThe primary purpose of this process is to find\ntoo tight spacings or glyph collisions caused by the kernings.\n\nThis tool has heuristic rules to determine\nthe applicability of the spacings using the glyph metrics,\nbut assumes that full-width punctuation glyphs have enough internal spacings\naccording to linguistic conventions\nas in [UAX#50](http://unicode.org/reports/tr50/#vertical_alternates)\nor in [CLREQ](https://w3c.github.io/clreq/#h-punctuation_adjustment_space).\nUnfortunately, not all fonts follow the conventions.\n\nTo run the visual test:\n\n1. Add the test font to the font list\n   in the top `\u003cscript\u003e` block of [`tests/test.html`](tests/test.html).\n2. Open it in your browser.\n3. Check \"Fullwidth\", \"Upright\", and \"Hide same size\" check boxes.\n\nHere is the check list and tips:\n\n* Find where glyphs are too tight or collide\n  when the feature is on but look fine without the feature.\n  - Quotation marks can collide most often,\n    especially in vertical flow but sometimes in horizontal flow too.\n  - \"Open+Open\" and \"Close+Close\" are more likely to collide than other pairs.\n  - Select glyphs to check how much inks overflow the glyph metrics.\n* Test both horizontal and vertical flows\n  by flipping the \"Vertical\" checkbox.\n\nOther controls in the test are not mandatory,\nbut they may be useful in following cases.\n\n* Uncheck \"Hide same size\" to see cases where kernings are not applied\n  by the built-in rules.\n  They are usually fine.\n  In most cases, they are because the glyphs are missing,\n  they are not full-width,\n  or the pair should not apply for the script of the font.\n  The test file contaisn code poitns for all East Asian scripts,\n  but not all code points should apply spacings for all script.\n* The \"Language\" list does not matter in most cases,\n  except when the font supports multiple locales,\n  such as Noto CJK.\n* The \"Fullwidth\" feature can change glyphs,\n  but in most cases,\n  if glyphs look ok with the feature on,\n  they should be ok with the feature off.\n* The \"Upright\" feature is only valid in the vertical flow.\n  You can just check it on,\n  for the same reason as the \"Fullwidth\" feature.\n* The \"Characters\" input fields can change the test cases.\n  You don't have to change them unless you have specific needs.\n\n## Releasing\n\nSee https://googlefonts.github.io/python#make-a-release.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgooglefonts%2Fchws_tool","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgooglefonts%2Fchws_tool","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgooglefonts%2Fchws_tool/lists"}