Metadata-Version: 2.4
Name: twat-image
Version: 2.7.9
Summary: A Python utility for converting images to include alpha channels based on grayscale values, and other image manipulations.
Project-URL: Documentation, https://github.com/twardoch/image-alpha-utils#readme
Project-URL: Issues, https://github.com/twardoch/image-alpha-utils/issues
Project-URL: Source, https://github.com/twardoch/image-alpha-utils
Author-email: Adam Twardoch <adam+github@twardoch.com>
License-Expression: MIT
License-File: LICENSE
Keywords: alpha,conversion,graphics,image,utility
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.10
Requires-Dist: fire
Requires-Dist: numpy
Requires-Dist: pillow
Provides-Extra: all
Requires-Dist: fire; extra == 'all'
Requires-Dist: numpy; extra == 'all'
Requires-Dist: pillow; extra == 'all'
Requires-Dist: twat-fs[all]>=2.7.7; extra == 'all'
Requires-Dist: twat>=1.8.1; extra == 'all'
Provides-Extra: dev
Requires-Dist: mypy>=1.15.0; extra == 'dev'
Requires-Dist: pre-commit>=4.1.0; extra == 'dev'
Requires-Dist: ruff>=0.9.6; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5.0; extra == 'docs'
Requires-Dist: mkdocs>=1.6.0; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.27.0; extra == 'docs'
Provides-Extra: test
Requires-Dist: pytest-benchmark[histogram]>=5.1.0; extra == 'test'
Requires-Dist: pytest-cov>=6.0.0; extra == 'test'
Requires-Dist: pytest-xdist>=3.6.1; extra == 'test'
Requires-Dist: pytest>=8.3.4; extra == 'test'
Provides-Extra: upload
Requires-Dist: twat-fs[all]>=2.7.7; extra == 'upload'
Description-Content-Type: text/markdown

# twat-image

`twat-image` is the image domain package for the `twat` plugin ecosystem. It owns deterministic image operations and delegates AI generation or editing to `twat_genai` when that optional package is installed.

## Install

```bash
pip install twat-image
```

For development:

```bash
pip install -e ".[test,dev]"
```

## Python API

```python
from PIL import Image
from twat_image import igray2alpha, scale_image, read_image_metadata

image = Image.open("logo.png")
mask = igray2alpha(image, color="black", white_point=0.9, black_point=0.1)
mask.save("logo-alpha.png")

small = scale_image(image, width=512)
small.save("logo-512.png")

print(read_image_metadata("logo.png"))
```

Deterministic helpers include:

- `igray2alpha` / `gray2alpha`: grayscale-derived alpha masks.
- `alpha_from_diff`: alpha from the grayscale difference of two images.
- `normalize_image`: auto-contrast and optional equalization.
- `scale_image`, `crop_image`, `outcrop_image`: basic geometry.
- `convert_image`: format conversion through Pillow.
- `read_image_metadata`, `find_duplicate_images`: dimensions, format, and average-hash duplicate grouping.

## CLI

```bash
python -m twat_image --help
python -m twat_image gray2alpha input.jpg output.png --color black
python -m twat_image scale input.png output.png --width 512
python -m twat_image crop input.png crop.png 10 10 300 300
python -m twat_image outcrop input.png padded.png --left 40 --right 40 --top 20 --bottom 20
python -m twat_image normalize input.png normalized.png
python -m twat_image metadata input.png
```

The legacy `imagealpha` script remains as a compatibility alias for the original grayscale-to-alpha command.

## AI image boundary

`twat-image` does not contain provider clients. Use `generate_image()` and `edit_image()` as thin adapters to `twat_genai`:

```python
from twat_image import generate_image, edit_image

generate_image("a black cat drawn as clean vector art", output_dir="out")
edit_image("make it look like ink on paper", "input.png", output_dir="out")
```

Install and configure `twat-genai` separately for OpenAI, Gemini/Nano Banana, Fal, or future provider engines.

## Reference scripts

Reusable deterministic work from `reference/bin-img-vid/imggray2alpha`, `imgalphafromdiff.py`, `imgscale.py`, `imgcrop`, `imgoutcrop`, and `imgdedup` is represented by the APIs above. Provider-heavy scripts such as `imgquotio.py` and `imgnanobanatrans.py` belong in `twat_genai`; this package only calls that boundary.

Local shell workflow glue remains in `reference/bin-img-vid/` because it encodes workstation-specific pipelines rather than reusable library behavior.
