Metadata-Version: 2.4
Name: krita4python
Version: 0.1.2.post20260512
Summary: Pure-Python reader and writer for Krita (.kra) files. No Krita install required.
Author: Quanvm0501alt1
License: GPL-3.0-or-later
Project-URL: Homepage, https://codeberg.org/Quanvm0501alt1/Krita4Python
Project-URL: Issues, https://codeberg.org/Quanvm0501alt1/Krita4Python/issues
Keywords: krita,kra,layers,image,live2d,openraster
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Pillow>=9.0
Provides-Extra: speed
Requires-Dist: numpy>=1.22; extra == "speed"
Requires-Dist: python-lzf>=0.2.4; extra == "speed"
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Dynamic: license-file

# krita4python

Pure-Python reader **and** writer for Krita's native `.kra` files. No Krita install required, no C extension required, and it runs on every Python that Pillow supports (3.9 – 3.13+).

`kritapy`/`kra-py` on PyPI is write-only and breaks on Python 3.12+; `krita4python` is a clean-room reimplementation against the [documented format](https://github.com/2shady4u/godot-kra-psd-importer/blob/master/docs/KRA_FORMAT.md) so it stays working.

## Install

```
pip install krita4python
```

Optional speedups (NumPy for the planar/interleaved conversion, `python-lzf` for the C LZF codec):

```
pip install "krita4python[speed]"
```

Everything still works without them, it's just slower on big layers.

## Read a .kra

```python
from krita4python import read_kra

doc = read_kra("character.kra")
print(doc.width, doc.height)
for layer in doc.iter_paint_layers():
    print(layer.name, layer.x, layer.y, layer.opacity, layer.visible)
    if layer.image is not None:
        layer.image.save(f"{layer.name}.png")
```

`doc.layers` is a tree of `KraGroup`/`KraLayer` nodes in **back-to-front** order. `layer.image` is a Pillow `RGBA` image sized to the layer's tight bounding box; `layer.x`/`y` is its canvas offset.

## Write a .kra

```python
from PIL import Image
from krita4python import write_kra, KraDocument, KraLayer

doc = KraDocument(
    width=1024, height=1024,
    layers=[
        KraLayer(name="bg", image=Image.open("bg.png")),
        KraLayer(name="char", image=Image.open("char.png"), x=128, y=64),
    ],
)
write_kra("out.kra", doc)
```

The resulting file opens in Krita 5.x and round-trips back through `read_kra`.

## CLI

```
krita4python extract character.kra -o ./layers/
krita4python pack ./layers/ -o repacked.kra
```

## What's supported

* RGBA / 8-bit paint layers (the format used by 99%+ of `.kra` files).
* Group layers, nesting, visibility, opacity, composite-op, layer offsets.
* `mergedimage.png` and `preview.png` (auto-generated on write).
* Tile-level LZF compression with the documented planar BGRA layout.

## What's NOT supported (yet)

* Non-8-bit color depths (16f / 32f).
* Non-RGBA colorspaces (CMYK, grayscale).
* Filter, vector, transform-mask, file-reference, clone layers (we surface their metadata but not pixels).
* Per-layer ICC profiles.

PRs welcome.

## Why does this exist

OpenLive2D needed real `.kra` reading on Python 3.13 (where `kritapy` raises a dataclass error on import). Rather than depend on Krita running headlessly, `krita4python` reimplements the format. License is GPL-3.0.
