PyScreeze

https://pypi.org/project/PyScreeze/
Admin
PyScreeze is a simple, cross-platform screenshot module for Python that can capture screenshots,...
Tokens:4,373
Snippets:44
Trust Score:10
Update:6 months ago
Show doc for...
Tokens:
Raw
### Locate image on screen and click

Source: https://pypi.org/project/PyScreeze/1.0.1

Locate an image on the screen to get its bounding box, then calculate the center to perform a click action.

```python
>>> import pyscreeze, pyautogui
>>> button7location = pyscreeze.locateOnScreen('calc7key.png')
>>> button7location
(1416, 562, 50, 41)
>>> button7x, button7y = pyscreeze.center(button7location)
>>> button7x, button7y
(1441, 582)
>>> pyautogui.click(button7x, button7y)  # clicks the center of where the 7 button was found
```

```python
>>> import pyscreeze, pyautogui
>>> x, y = pyscreeze.locateCenterOnScreen('calc7key.png')
>>> pyautogui.click(x, y)
```

--------------------------------

### Pixel Matching

Source: https://pypi.org/project/PyScreeze/1.0.1

PyScreeze allows you to get pixel colors and check if pixels match a specific color, with an optional tolerance.

```APIDOC
## Pixel Matching

### `getpixel((x, y))`
- **Description**: Returns the RGB color of a pixel at the given coordinates from a screenshot.

### `pixel(x, y)`
- **Description**: A wrapper function to get the RGB color of a pixel at the given coordinates.

### `pixelMatchesColor(x, y, color_rgb, tolerance=0)`
- **Description**: Checks if the pixel at the given coordinates matches the specified RGB color. An optional tolerance can be provided.
- **Parameters**:
  - `x` (integer) - Required - The X coordinate.
  - `y` (integer) - Required - The Y coordinate.
  - `color_rgb` (tuple) - Required - The RGB color tuple (e.g., (255, 0, 0)).
  - `tolerance` (integer) - Optional - The allowed variation for each RGB value.

### Example Usage:
```python
import pyscreeze

# Get the color of a pixel
print(pyscreeze.pixel(100, 200))

# Check if a pixel matches a specific color
print(pyscreeze.pixelMatchesColor(100, 200, (130, 135, 144)))

# Check with tolerance
print(pyscreeze.pixelMatchesColor(100, 200, (140, 125, 134), tolerance=10))
```
```

--------------------------------

### Get Pixel Color using PyScreeze Function

Source: https://pypi.org/project/PyScreeze

A wrapper function to get the RGB color of a specific pixel at given coordinates. Requires importing pyscreeze.

```python
import pyscreeze
pyscreeze.pixel(100, 200)
```

--------------------------------

### Get Pixel Color from Screenshot

Source: https://pypi.org/project/PyScreeze

Captures a screenshot and retrieves the RGB color of a specific pixel using the Image object's getpixel() method. Requires importing pyscreeze.

```python
import pyscreeze
im = pyscreeze.screenshot()
im.getpixel((100, 200))
```

--------------------------------

### Retrieve pixel color

Source: https://pypi.org/project/PyScreeze/1.0.1

Get the RGB color of a specific pixel using either the Image object or the direct pixel function.

```python
>>> import pyscreeze
>>> im = pyscreeze.screenshot()
>>> im.getpixel((100, 200))
(130, 135, 144)
```

```python
>>> import pyscreeze
>>> pyscreeze.pixel(100, 200)
(130, 135, 144)
```

--------------------------------

### Take a Screenshot and Save to File

Source: https://pypi.org/project/PyScreeze/1.0.1

Use `pyscreeze.screenshot()` to capture the entire screen and save it to a specified filename. This function returns an Image object.

```python
import pyscreeze
im1 = pyscreeze.screenshot()
im2 = pyscreeze.screenshot('my_screenshot.png')
```

--------------------------------

### Grayscale Matching

Source: https://pypi.org/project/PyScreeze/1.0.1

You can optionally enable grayscale matching for a potential speed increase, though it might lead to false positives.

```APIDOC
## Grayscale Matching

Optionally, you can pass `grayscale=True` to the locate functions to give a slight speedup (about 30%-ish). This desaturates the color from the images and screenshots, speeding up the locating but potentially causing false-positive matches.

### Example Usage:
```python
import pyscreeze

button7location = pyscreeze.locateOnScreen('calc7key.png', grayscale=True)
print(button7location)
```
```

--------------------------------

### Locate Image on Screen with Grayscale

Source: https://pypi.org/project/PyScreeze

Performs image location search on the screen using grayscale conversion for a potential speedup. May cause false positives. Requires importing pyscreeze.

```python
import pyscreeze
button7location = pyscreeze.locateOnScreen('calc7key.png', grayscale=True)
button7location
```

--------------------------------

### Locate all instances of an image

Source: https://pypi.org/project/PyScreeze/1.0.1

Use locateAllOnScreen to find multiple occurrences of an image, returning a generator or list of coordinates.

```python
>>> import pyscreeze
>>> for pos in pyscreeze.locateAllOnScreen('someButton.png')
...   print(pos)
...
(1101, 252, 50, 50)
(59, 481, 50, 50)
(1395, 640, 50, 50)
(1838, 676, 50, 50)
>>> list(pyscreeze.locateAllOnScreen('someButton.png'))
[(1101, 252, 50, 50), (59, 481, 50, 50), (1395, 640, 50, 50), (1838, 676, 50, 50)]
```

--------------------------------

### Locate Button on Screen and Click

Source: https://pypi.org/project/PyScreeze

Finds the location of an image on the screen and clicks its center. Requires importing pyscreeze and pyautogui. The locateOnScreen function returns coordinates or None if not found.

```python
import pyscreeze, pyautogui
button7location = pyscreeze.locateOnScreen('calc7key.png')
button7location
button7x, button7y = pyscreeze.center(button7location)
button7x, button7y
pyautogui.click(button7x, button7y)  # clicks the center of where the 7 button was found
```

--------------------------------

### Locate image with grayscale matching

Source: https://pypi.org/project/PyScreeze/1.0.1

Enable grayscale matching to improve performance by desaturating images during the search process.

```python
>>> import pyscreeze
>>> button7location = pyscreeze.locateOnScreen('calc7key.png', grayscale=True)
>>> button7location
(1416, 562, 50, 41)
```

--------------------------------

### Locate Center of Image on Screen and Click

Source: https://pypi.org/project/PyScreeze

Directly finds the center coordinates of an image on the screen and clicks it. This is a convenient function for common use cases. Requires importing pyscreeze and pyautogui.

```python
import pyscreeze, pyautogui
x, y = pyscreeze.locateCenterOnScreen('calc7key.png')
pyautogui.click(x, y)
```

--------------------------------

### Locate Functions Overview

Source: https://pypi.org/project/PyScreeze/1.0.1

PyScreeze provides several functions to locate images on the screen. These functions return coordinates or generators yielding coordinates of the found images.

```APIDOC
## Locate Functions

You can visually locate something on the screen if you have an image file of it. The return value is a 4-integer tuple: (left, top, width, height). This tuple can be passed to center() to get the X and Y coordinates at the center of this region. If the image can’t be found on the screen, locateOnScreen() returns None.

### `locateOnScreen(image, grayscale=False)`
- **Description**: Returns the (left, top, width, height) coordinate of the first found instance of the image on the screen. Returns None if not found.
- **Parameters**:
  - `image` (string) - Required - The image file to locate.
  - `grayscale` (boolean) - Optional - If True, performs grayscale matching for a potential speedup.

### `locateCenterOnScreen(image, grayscale=False)`
- **Description**: Returns the (x, y) coordinates of the center of the first found instance of the image on the screen. Returns None if not found.
- **Parameters**:
  - `image` (string) - Required - The image file to locate.
  - `grayscale` (boolean) - Optional - If True, performs grayscale matching for a potential speedup.

### `locateAllOnScreen(image, grayscale=False)`
- **Description**: Returns a generator that yields (left, top, width, height) tuples for all occurrences of the image on the screen.
- **Parameters**:
  - `image` (string) - Required - The image file to locate.
  - `grayscale` (boolean) - Optional - If True, performs grayscale matching for a potential speedup.

### `locate(needleImage, haystackImage, grayscale=False)`
- **Description**: Returns the (left, top, width, height) coordinate of the first found instance of `needleImage` within `haystackImage`. Returns None if not found.
- **Parameters**:
  - `needleImage` (string) - Required - The image file to locate.
  - `haystackImage` (string) - Required - The image file to search within.
  - `grayscale` (boolean) - Optional - If True, performs grayscale matching for a potential speedup.

### `locateAll(needleImage, haystackImage, grayscale=False)`
- **Description**: Returns a generator that yields (left, top, width, height) tuples for all occurrences of `needleImage` within `haystackImage`.
- **Parameters**:
  - `needleImage` (string) - Required - The image file to locate.
  - `haystackImage` (string) - Required - The image file to search within.
  - `grayscale` (boolean) - Optional - If True, performs grayscale matching for a potential speedup.

### Example Usage:
```python
import pyscreeze, pyautogui

# Locate the center of an image and click it
x, y = pyscreeze.locateCenterOnScreen('calc7key.png')
pyautogui.click(x, y)

# Find all occurrences of an image
for pos in pyscreeze.locateAllOnScreen('someButton.png'):
  print(pos)
```
```

--------------------------------

### Verify pixel color match

Source: https://pypi.org/project/PyScreeze/1.0.1

Check if a pixel matches a specific color, optionally using a tolerance value for color variance.

```python
>>> import pyscreeze
>>> pyscreeze.pixelMatchesColor(100, 200, (130, 135, 144))
True
>>> pyscreeze.pixelMatchesColor(100, 200, (0, 0, 0))
False
```

```python
>>> import pyscreeze
>>> pyscreeze.pixelMatchesColor(100, 200, (130, 135, 144))
True
>>> pyscreeze.pixelMatchesColor(100, 200, (140, 125, 134))
False
>>> pyscreeze.pixelMatchesColor(100, 200, (140, 125, 134), tolerance=10)
True
```

--------------------------------

### Take a Screenshot of a Specific Region

Source: https://pypi.org/project/PyScreeze/1.0.1

Capture a portion of the screen by providing a four-integer tuple to the `region` keyword argument in `pyscreeze.screenshot()`. The tuple represents (left, top, width, height).

```python
import pyscreeze
im = pyscreeze.screenshot(region=(0,0, 300, 400))
```

--------------------------------

### Find All Occurrences of an Image on Screen

Source: https://pypi.org/project/PyScreeze

Iterates through all occurrences of a specified image on the screen, yielding their coordinates. Can be used in a for loop or converted to a list. Requires importing pyscreeze.

```python
import pyscreeze
for pos in pyscreeze.locateAllOnScreen('someButton.png')
  print(pos)
list(pyscreeze.locateAllOnScreen('someButton.png'))
```

--------------------------------

### Check Pixel Color Match with Tolerance

Source: https://pypi.org/project/PyScreeze

Checks if a pixel at given coordinates matches a specified RGB color tuple within a given tolerance. The tolerance value allows for slight variations in RGB values. Requires importing pyscreeze.

```python
import pyscreeze
pyscreeze.pixelMatchesColor(100, 200, (130, 135, 144))
pyscreeze.pixelMatchesColor(100, 200, (140, 125, 134))
pyscreeze.pixelMatchesColor(100, 200, (140, 125, 134), tolerance=10)
```

--------------------------------

### Pixel Matching

Source: https://pypi.org/project/PyScreeze

Inspect individual pixel colors or check if a pixel matches a specific color, with an option to set a tolerance for color variations.

```APIDOC
## Pixel Matching

PyScreeze provides functions to get pixel colors and check for color matches.

### Get Pixel Color

- **`screenshot().getpixel((x, y))`**: Returns the RGB color of a pixel at the given coordinates from a screenshot.
- **`pixel(x, y)`**: A wrapper function that returns the RGB color of the pixel at the given coordinates.

```python
import pyscreeze

# Get RGB color of pixel at (100, 200)
pixel_color = pyscreeze.screenshot().getpixel((100, 200))
print(pixel_color) # Example output: (130, 135, 144)

pixel_color_direct = pyscreeze.pixel(100, 200)
print(pixel_color_direct) # Example output: (130, 135, 144)
```

### Pixel Color Matching

- **`pixelMatchesColor(x, y, expected_rgb_tuple, tolerance=0)`**: Returns `True` if the pixel at `(x, y)` matches the `expected_rgb_tuple`, considering the optional `tolerance`.

- **Parameters**:
  - `x` (int): The X coordinate of the pixel.
  - `y` (int): The Y coordinate of the pixel.
  - `expected_rgb_tuple` (tuple): A 3-integer tuple representing the expected RGB color (e.g., `(R, G, B)`).
  - `tolerance` (int): The allowed variation for each RGB value. Defaults to `0`.

```python
import pyscreeze

# Check if pixel at (100, 200) matches (130, 135, 144)
matches = pyscreeze.pixelMatchesColor(100, 200, (130, 135, 144))
print(matches) # Expected output: True

# Check with tolerance
matches_with_tolerance = pyscreeze.pixelMatchesColor(100, 200, (140, 125, 134), tolerance=10)
print(matches_with_tolerance) # Expected output: True
```
```

--------------------------------

### Check if Pixel Matches Specific Color

Source: https://pypi.org/project/PyScreeze

Verifies if a pixel at given coordinates matches a specified RGB color tuple. Returns True if it matches, False otherwise. Requires importing pyscreeze.

```python
import pyscreeze
pyscreeze.pixelMatchesColor(100, 200, (130, 135, 144))
pyscreeze.pixelMatchesColor(100, 200, (0, 0, 0))
```
Tokens:
Raw