Metadata-Version: 2.4
Name: screenimagedetection
Version: 0.1.0
Summary: Screen template-matching (find an image on screen) built on cv2, numpy and mss
Author-email: intensDevelopment <intens.development.xyz@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/inntens/screenimagedetection
Keywords: screen,template-matching,opencv,image-detection,automation
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: opencv-python
Requires-Dist: numpy
Requires-Dist: mss
Dynamic: license-file

# screenimagedetection

Find an image on your screen via template matching (`cv2` + `numpy` + `mss`).

Missing dependencies (`opencv-python`, `numpy`, `mss`) are installed
automatically on first import if they're not already present.

## Install

```bash
pip install screenimagedetection
```

## Usage

```python
import screenimagedetection

result = screenimagedetection.screenimagedetection(
    screen=1,                 # monitor index (mss.monitors[1]) OR a monitor dict
    where="bottom_half",
    image_path="templates/button.png",
    threshold=0.7,
)

if result["found"]:
    print(result["score"], result["x"], result["y"])
```

### `where` options

Every named region is really just a cell of a grid over the monitor:

- **1x2 / 2x1 grid** -> halves: `left_half`, `right_half`, `top_half`, `bottom_half`
  (aliases without underscores also work, e.g. `tophalf`, `lefthalf`)
- **2x2 grid** -> quadrants: `top_left_quadrant`, `top_right_quadrant`,
  `bottom_left_quadrant`, `bottom_right_quadrant`
  (aliases like `lefttopquadrant` also work)
- **1x3 grid** -> vertical thirds (columns): `left_third`, `middle_third`, `right_third`
- **3x1 grid** -> horizontal thirds (rows): `top_third`, `middle_third_horizontal`, `bottom_third`
- **3x3 grid** -> nine cells: `top_left_third`, `top_middle_third`, `top_right_third`,
  `middle_left_third`, `middle_middle_third`, `middle_right_third`,
  `bottom_left_third`, `bottom_middle_third`, `bottom_right_third`
  (aliases without underscores also work, e.g. `topleftthird`, `centerthird` for the middle cell)
- `entire` -> the whole monitor

### Custom regions

Instead of a preset name, `where` also accepts:

- **A grid cell** as `(row, col, rows, cols)`, 0-indexed, for any grid size you like:

  ```python
  # row 0, column 2 of a 4x4 grid
  screenimagedetection.screenimagedetection(
      screen=1, where=(0, 2, 4, 4), image_path="templates/button.png"
  )
  ```

- **A fully custom rectangle** as fractions (0.0-1.0) of the monitor:

  ```python
  screenimagedetection.screenimagedetection(
      screen=1,
      where={"left_frac": 0.1, "top_frac": 0.2, "width_frac": 0.5, "height_frac": 0.3},
      image_path="templates/button.png",
  )
  ```

### Return value

```python
{
  "found": bool,
  "score": float,
  "x": int, "y": int,           # top-left corner, absolute screen coordinates
  "w": int, "h": int,
  "center_x": int, "center_y": int,
}
```

## License

MIT
