Metadata-Version: 2.4
Name: pyvisionauto
Version: 0.1.1
Summary: PyVisionAuto: Cross-platform desktop automation toolkit with visual image matching, mouse/keyboard control, and screen recording
Author: PyVisionAuto contributors
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://pypi.org/project/pyvisionauto/
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Microsoft :: Windows
Classifier: Environment :: X11 Applications
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: license.dat
Requires-Dist: opencv-python>=4.8.0
Requires-Dist: mss>=9.0.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: pyautogui>=0.9.54
Requires-Dist: pillow>=10.0.0
Provides-Extra: test
Requires-Dist: pytest>=8.0; extra == "test"
Dynamic: license-file

# PyVisionAuto

[![PyPI version](https://img.shields.io/pypi/v/pyvisionauto.svg)](https://pypi.org/project/pyvisionauto/)
![Python](https://img.shields.io/pypi/pyversions/pyvisionauto)
![Platform](https://img.shields.io/badge/platform-Linux%20%7C%20Windows-blue)

**PyVisionAuto** is an end-to-end desktop automation toolkit.
It is centered on visual image matching and also includes screen recording, mouse automation, and keyboard automation capabilities.

## Scope

- Linux (X11 session) and Windows
- Real physical display required

## Install

```bash
pip install pyvisionauto
```

## System dependencies

### Linux

- python3-tk (for border overlay highlight)
- xdotool (preferred for window activation)
- wmctrl (fallback for window activation)
- ffmpeg (optional, only for recording APIs; install via `sudo apt install ffmpeg`)

### Windows

- tkinter (bundled with most Python installations on Windows)
- ffmpeg (optional, only for recording APIs; must be installed and added to system PATH)

> **Installing ffmpeg on Windows:** Download from [ffmpeg.org](https://ffmpeg.org/download.html), extract the archive, and add the `bin` folder to your system `PATH`.

## Quick start

```python
from pyvisionauto import Screen

screen = Screen()
screen.wait("login_button.png", timeout=10).highlight().click()
```

### Activate a window before matching

```python
screen.activate_window("Calculator")
screen.click("button.png")
```

## Runtime screenshot

Highlighted match region during runtime:

![PyVisionAuto runtime screenshot with highlighted region](screenshot.png)

## Platform differences

| Feature | Linux | Windows |
|---|---|---|
| Screen capture & template matching | Supported | Supported |
| Mouse / keyboard automation | Supported | Supported |
| Highlight overlay | Supported | Supported |
| Window activation | xdotool / wmctrl | pyautogui (pygetwindow) |
| Screen recording | ffmpeg + x11grab | ffmpeg + gdigrab |

> Screen recording requires ffmpeg installed and added to system PATH. Linux uses `x11grab`, Windows uses `gdigrab`.

## Notes

- Wayland-only and headless environments are not currently supported.
- On Windows with high-DPI scaling, coordinate accuracy may be affected.
