Metadata-Version: 2.2
Name: kle-scraper
Version: 0.1.1
Summary: kle-scraper is a Python library for scraping the key top images of keyboard-layout-editor.com (KLE).
Author-email: NAKAZATO Hajime <hajime@kaoriha.org>
License: MIT License
        
        Copyright (c) 2021-2025 NAKAZATO Hajime
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Bug Tracker, https://github.com/hajimen/kle_scraper/issues
Project-URL: Changelog, https://github.com/hajimen/kle_scraper/blob/master/CHANGELOG.md
Project-URL: Repository, https://github.com/hajimen/kle_scraper.git
Keywords: keyboard-layout-editor.com,KLE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cef-capi-py
Requires-Dist: Pillow>=10.4.0
Requires-Dist: pykle-serial>=0.0.2

# kle-scraper

**kle-scraper** is a Python library for scraping the key top images of 
[keyboard-layout-editor.com (KLE)](http://www.keyboard-layout-editor.com/).

It renders KLE screen by CEF (Chromium Embedded Framework) and captures it. 
It contains KLE codes and works offline, of course.

## Limitations

- No support for custom styles. Key color is always white.
- Front legend is ignored.
- Legend color is equal to KLE screen, not the value in properties. KLE screen color is 
a bit paler than the value in properties.
- It handles non-rectangle keys (big ass enter and ISO enter) awkwardly. Big ass enter image 
lacks the left bottom bulge and ISO enter contains the left bottom dent.
- Crop area isn't pixel-wise precise, especially about rotated keys. The precision is half pixel 
in KLE screen.
- It is non-reentrant (not multi-threaded).
- It is slow, especially when the layout has a lot of differently rotated keys.
- It cannot handle extraordinary large layout.

Available platforms:

- Windows x86-64
- macOS Intel and Apple Silicon
- Linux x86-64 (aarch64 has a problem now in CEF. See: [Dynamic loading of libcef.so on Linux ARM64 not possible anymore due to TLS size increase](https://github.com/chromiumembedded/cef/issues/3803))

## Installation

Grab your platform's wheel from [cef-capi-py release](https://github.com/hajimen/cef-capi-py/releases/tag/131.3.5) and `pip install` it.
I haven't uploaded the wheels to PyPI yet because now PyPI project is not processing support issues:
[File Limit Request: cef-capi-py - 180 MB](https://github.com/pypi/support/issues/5491).

```bash
pip install kle-scraper
```

## Usage

```python
import tempfile
from kle_scraper import scrape

with tempfile.TemporaryDirectory() as image_output_dir:
    keyboard = scrape(kle_json_filename, image_output_dir)
```

You can find `0.png`, `1.png` and more in `image_output_dir`. The filename number corresponds to 
`keyboard.keys`'s index. `keyboard` is an instance of `pykle_serial.Keyboard`.

Otherwise from command line,

```bash
python -m kle_scraper {kle_json_filename} {image_output_dir}
```

## Dimension of scraped images

Scraped images are magnified to 4x. On KLE screen, 1u key top has 42x42 px. 
Key layout pitch is 54x54 px. On scraped images, 1u key top (and image size) is 
168x168 px and 1u pitch is 216x216 px.

## License

MIT license.
