PyScreeze

Warnings

• breaking The default behavior of `locate` functions changed in version 1.0.0. They now raise `pyscreeze.ImageNotFoundException` when an image is not found, instead of returning `None`.
  Fix: Wrap calls to `locateOnScreen`, `locateCenterOnScreen`, `locateAllOnScreen`, and `locate` in a `try...except pyscreeze.ImageNotFoundException` block. Alternatively, set `pyscreeze.USE_IMAGE_NOT_FOUND_EXCEPTION = False` to revert to returning `None`.
• gotcha Pillow version compatibility is crucial. Older versions of Pillow have known security vulnerabilities. For Python 3.6+, Pillow >= 8.3.2 is recommended. For Python 3.7+ and Wayland support on Linux, Pillow >= 9.2.0 is needed.
  Fix: Ensure you are using an up-to-date Python version (3.6+) and install or upgrade Pillow to a secure and compatible version (e.g., `pip install --upgrade Pillow`). Consult `pyscreeze/setup.py` for precise version requirements per Python version.
• gotcha On Linux, PyScreeze often relies on external command-line tools for screenshots (e.g., `scrot` or `gnome-screenshot`) and may require `python3-xlib` for X11 environments. These must be installed separately via the system's package manager.
  Fix: Install necessary packages: `sudo apt install scrot` or `sudo apt install gnome-screenshot` (depending on system/preferences) and `sudo apt install python3-xlib` if using X11.
• gotcha When used with PyAutoGUI, a common issue is 'PyAutoGUI was unable to import PyScreeze' errors. This often indicates problems with PyScreeze or Pillow installations, or Python environment conflicts.
  Fix: Verify that both `pyscreeze` and `Pillow` are correctly installed and compatible with your Python version. Use virtual environments to prevent conflicts. If problems persist, try reinstalling both libraries.
• breaking The `pixelMatchesColor()` function in version 1.0.0 changed its argument signature. It no longer accepts a `(x, y)` tuple as the first argument; `x` and `y` must now be passed as separate arguments.
  Fix: Update calls from `pyscreeze.pixelMatchesColor((x, y), rgb_tuple)` to `pyscreeze.pixelMatchesColor(x, y, rgb_tuple)`.
• gotcha The `region` argument for `screenshot()` must be a tuple of exactly four integers (left, top, width, height). Non-integer values or incorrect lengths will raise an error.
  Fix: Always pass a tuple of four integers, e.g., `pyscreeze.screenshot(region=(10, 20, 100, 50))`.

Install

• pip install pyscreeze Install latest version

Imports

• pyscreeze

  import pyscreeze

  All functions are typically accessed directly from the `pyscreeze` module, e.g., `pyscreeze.screenshot()`.

Quickstart

This quickstart demonstrates how to take full or partial screenshots and how to locate an image on the screen using `screenshot()` and `locateOnScreen()`. The `locateOnScreen()` function returns a 4-integer tuple (left, top, width, height) if found, or raises an `ImageNotFoundException` if not found (default behavior since 1.0.0).

import pyscreeze

# Take a screenshot of the entire screen
im1 = pyscreeze.screenshot()
# Save a screenshot to a file
im2 = pyscreeze.screenshot('my_screenshot.png')

# Take a screenshot of a specific region (left, top, width, height)
# Ensure 'image_path.png' exists for locateOnScreen to work
try:
    region_screenshot = pyscreeze.screenshot(region=(0, 0, 300, 400))
    print(f"Screenshot of region saved as temporary file. Image object: {region_screenshot}")

    # Locate an image on the screen
    # Replace 'path/to/your/button.png' with an actual image file on your screen
    # Ensure an image 'button.png' is in the current directory or provide full path
    button_location = pyscreeze.locateOnScreen('button.png', confidence=0.8)
    if button_location:
        print(f"Button found at: {button_location}")
        center_coords = pyscreeze.center(button_location)
        print(f"Center of button: {center_coords}")
    else:
        print("Button not found on screen.")
except pyscreeze.ImageNotFoundException:
    print("Image not found on screen (expected for 'button.png' if not present).")
except FileNotFoundError:
    print("Ensure 'button.png' exists in the current directory or provide a full path.")
except Exception as e:
    print(f"An error occurred: {e}")