PyScreeze
=========
PyScreeze is a simple, cross-platform screenshot module for Python 3.
About
-----
PyScreeze can take screenshots, save them to files, and locates images within the screen. This is useful if you have a small image of, say, a button that needs to be clicked and want to locate it on the screen.
NOTE - PyScreeze depends on Pillow for screenshots, whose older versions have security issues. The only secure versions of Pillow are 8.3.2 and later. However, Pillow 8.3.2 only supports Python as far back as Python 3.6. If you are installing PyScreeze for Python 3.5 or earlier, be aware that there may be security issues with the version of Pillow it uses.
If Pillow is unavailable, there are fallback methods for each OS (screencapture for macOS, gnome-screenshot for Linux, etc.)
Special Notes About Ubuntu
==========================
If your Ubuntu system uses the older X11 window system, you must install Xlib by running `sudo apt install python3-xlib`. This will require the admin password for your computer.
The screenshot() Function
=========================
Calling `screenshot()` will return an Image object (see the Pillow or PIL module documentation for details). Passing a string of a filename will save the screenshot to a file as well as return it as an Image object.
>>> import pyscreeze
>>> im1 = pyscreeze.screenshot()
>>> im2 = pyscreeze.screenshot('my_screenshot.png')
On a 1920 x 1080 screen, the `screenshot()` function takes roughly 100 milliseconds - it's not fast but it's not slow.
There is also an optional `region` keyword argument, if you do not want a screenshot of the entire screen. You can pass a four-integer tuple of the left, top, width, and height of the region to capture:
>>> import pyscreeze
>>> im = pyscreeze.screenshot(region=(0,0, 300, 400))
The Locate Functions
====================
You can visually locate something on the screen if you have an image file of it. You can call the `locateOnScreen('calc7key.png')` function to get the screen coordinates of the 7 button for a calculator app. 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`. (PyAutoGUI is a module that simulates mouse clicks.)
>>> 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
The `locateCenterOnScreen()` function is probably the one you want to use most often:
>>> import pyscreeze, pyautogui
>>> x, y = pyscreeze.locateCenterOnScreen('calc7key.png')
>>> pyautogui.click(x, y)
On a 1920 x 1080 screen, the locate function calls take about 1 or 2 seconds. This may be too slow for action video games, but works for most purposes and applications.
If speed is important, install the optional opencv library (`pip install cv2`). The `locateAll` computation will use it if available, and take less than 1 millisecond to find all matches in a full-screen search. (This does not include the time required to capture a screenshot.)
There are several "locate" functions. They all start looking at the top-left corner of the screen (or image) and look to the left and then down. The arguments can either be a
- `locateOnScreen(image, grayscale=False)` - Returns (left, top, width, height) coordinate of first found instance of the `image` on the screen. Returns None if not found on the screen.
- `locateCenterOnScreen(image, grayscale=False)` - Returns (x, y) coordinates of the center of the first found instance of the `image` on the screen. Returns None if not found on the screen.
- `locateAllOnScreen(image, grayscale=False)` - Returns a generator that yields (left, top, width, height) tuples for where the image is found on the screen.
- `locate(needleImage, haystackImage, grayscale=False)` - Returns (left, top, width, height) coordinate of first found instance of `needleImage` in `haystackImage`. Returns None if not found on the screen.
- `locateAll(needleImage, haystackImage, grayscale=False)` - Returns a generator that yields (left, top, width, height) tuples for where `needleImage` is found in `haystackImage`.
The "locate all" functions can be used in for loops or passed to `list()`:
>>> 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)]
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.
>>> import pyscreeze
>>> button7location = pyscreeze.locateOnScreen('calc7key.png', grayscale=True)
>>> button7location
(1416, 562, 50, 41)
Pixel Matching
--------------
To obtain the RGB color of a pixel in a screenshot, use the Image object's `getpixel()` method:
>>> import pyscreeze
>>> im = pyscreeze.screenshot()
>>> im.getpixel((100, 200))
(130, 135, 144)
Or as a single function, call the `pixel()` PyScreeze function, which is a wrapper for the previous calls:
>>> import pyscreeze
>>> pyscreeze.pixel(100, 200)
(130, 135, 144)
If you just need to verify that a single pixel matches a given pixel, call the `pixelMatchesColor()` function, passing it the X coordinate, Y coordinate, and RGB tuple of the color it represents:
>>> import pyscreeze
>>> pyscreeze.pixelMatchesColor(100, 200, (130, 135, 144))
True
>>> pyscreeze.pixelMatchesColor(100, 200, (0, 0, 0))
False
The optional `tolerance` keyword argument specifies how much each of the red, green, and blue values can vary while still matching:
>>> 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
Support
-------
If you find this project helpful and would like to support its development, [consider donating to its creator on Patreon](https://www.patreon.com/AlSweigart).
Raw data
{
"_id": null,
"home_page": "https://github.com/asweigart/pyscreeze",
"name": "PyScreeze",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "screenshot screen screencap capture scrot screencapture image",
"author": "Al Sweigart",
"author_email": "al@inventwithpython.com",
"download_url": "https://files.pythonhosted.org/packages/ee/f0/cb456ac4f1a73723d5b866933b7986f02bacea27516629c00f8e7da94c2d/pyscreeze-1.0.1.tar.gz",
"platform": null,
"description": "PyScreeze\r\n=========\r\n\r\nPyScreeze is a simple, cross-platform screenshot module for Python 3.\r\n\r\nAbout\r\n-----\r\n\r\nPyScreeze can take screenshots, save them to files, and locates images within the screen. This is useful if you have a small image of, say, a button that needs to be clicked and want to locate it on the screen.\r\n\r\nNOTE - PyScreeze depends on Pillow for screenshots, whose older versions have security issues. The only secure versions of Pillow are 8.3.2 and later. However, Pillow 8.3.2 only supports Python as far back as Python 3.6. If you are installing PyScreeze for Python 3.5 or earlier, be aware that there may be security issues with the version of Pillow it uses.\r\n\r\nIf Pillow is unavailable, there are fallback methods for each OS (screencapture for macOS, gnome-screenshot for Linux, etc.)\r\n\r\nSpecial Notes About Ubuntu\r\n==========================\r\n\r\nIf your Ubuntu system uses the older X11 window system, you must install Xlib by running `sudo apt install python3-xlib`. This will require the admin password for your computer.\r\n\r\nThe screenshot() Function\r\n=========================\r\n\r\nCalling `screenshot()` will return an Image object (see the Pillow or PIL module documentation for details). Passing a string of a filename will save the screenshot to a file as well as return it as an Image object.\r\n\r\n >>> import pyscreeze\r\n >>> im1 = pyscreeze.screenshot()\r\n >>> im2 = pyscreeze.screenshot('my_screenshot.png')\r\n\r\nOn a 1920 x 1080 screen, the `screenshot()` function takes roughly 100 milliseconds - it's not fast but it's not slow.\r\n\r\nThere is also an optional `region` keyword argument, if you do not want a screenshot of the entire screen. You can pass a four-integer tuple of the left, top, width, and height of the region to capture:\r\n\r\n >>> import pyscreeze\r\n >>> im = pyscreeze.screenshot(region=(0,0, 300, 400))\r\n\r\nThe Locate Functions\r\n====================\r\n\r\nYou can visually locate something on the screen if you have an image file of it. You can call the `locateOnScreen('calc7key.png')` function to get the screen coordinates of the 7 button for a calculator app. 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`. (PyAutoGUI is a module that simulates mouse clicks.)\r\n\r\n >>> import pyscreeze, pyautogui\r\n >>> button7location = pyscreeze.locateOnScreen('calc7key.png')\r\n >>> button7location\r\n (1416, 562, 50, 41)\r\n >>> button7x, button7y = pyscreeze.center(button7location)\r\n >>> button7x, button7y\r\n (1441, 582)\r\n >>> pyautogui.click(button7x, button7y) # clicks the center of where the 7 button was found\r\n\r\nThe `locateCenterOnScreen()` function is probably the one you want to use most often:\r\n\r\n >>> import pyscreeze, pyautogui\r\n >>> x, y = pyscreeze.locateCenterOnScreen('calc7key.png')\r\n >>> pyautogui.click(x, y)\r\n\r\nOn a 1920 x 1080 screen, the locate function calls take about 1 or 2 seconds. This may be too slow for action video games, but works for most purposes and applications.\r\n\r\nIf speed is important, install the optional opencv library (`pip install cv2`). The `locateAll` computation will use it if available, and take less than 1 millisecond to find all matches in a full-screen search. (This does not include the time required to capture a screenshot.)\r\n\r\nThere are several \"locate\" functions. They all start looking at the top-left corner of the screen (or image) and look to the left and then down. The arguments can either be a\r\n\r\n- `locateOnScreen(image, grayscale=False)` - Returns (left, top, width, height) coordinate of first found instance of the `image` on the screen. Returns None if not found on the screen.\r\n\r\n- `locateCenterOnScreen(image, grayscale=False)` - Returns (x, y) coordinates of the center of the first found instance of the `image` on the screen. Returns None if not found on the screen.\r\n\r\n- `locateAllOnScreen(image, grayscale=False)` - Returns a generator that yields (left, top, width, height) tuples for where the image is found on the screen.\r\n\r\n- `locate(needleImage, haystackImage, grayscale=False)` - Returns (left, top, width, height) coordinate of first found instance of `needleImage` in `haystackImage`. Returns None if not found on the screen.\r\n\r\n- `locateAll(needleImage, haystackImage, grayscale=False)` - Returns a generator that yields (left, top, width, height) tuples for where `needleImage` is found in `haystackImage`.\r\n\r\nThe \"locate all\" functions can be used in for loops or passed to `list()`:\r\n\r\n >>> import pyscreeze\r\n >>> for pos in pyscreeze.locateAllOnScreen('someButton.png')\r\n ... print(pos)\r\n ...\r\n (1101, 252, 50, 50)\r\n (59, 481, 50, 50)\r\n (1395, 640, 50, 50)\r\n (1838, 676, 50, 50)\r\n >>> list(pyscreeze.locateAllOnScreen('someButton.png'))\r\n [(1101, 252, 50, 50), (59, 481, 50, 50), (1395, 640, 50, 50), (1838, 676, 50, 50)]\r\n\r\nGrayscale Matching\r\n------------------\r\n\r\nOptionally, 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.\r\n\r\n >>> import pyscreeze\r\n >>> button7location = pyscreeze.locateOnScreen('calc7key.png', grayscale=True)\r\n >>> button7location\r\n (1416, 562, 50, 41)\r\n\r\nPixel Matching\r\n--------------\r\n\r\nTo obtain the RGB color of a pixel in a screenshot, use the Image object's `getpixel()` method:\r\n\r\n >>> import pyscreeze\r\n >>> im = pyscreeze.screenshot()\r\n >>> im.getpixel((100, 200))\r\n (130, 135, 144)\r\n\r\nOr as a single function, call the `pixel()` PyScreeze function, which is a wrapper for the previous calls:\r\n\r\n >>> import pyscreeze\r\n >>> pyscreeze.pixel(100, 200)\r\n (130, 135, 144)\r\n\r\nIf you just need to verify that a single pixel matches a given pixel, call the `pixelMatchesColor()` function, passing it the X coordinate, Y coordinate, and RGB tuple of the color it represents:\r\n\r\n >>> import pyscreeze\r\n >>> pyscreeze.pixelMatchesColor(100, 200, (130, 135, 144))\r\n True\r\n >>> pyscreeze.pixelMatchesColor(100, 200, (0, 0, 0))\r\n False\r\n\r\nThe optional `tolerance` keyword argument specifies how much each of the red, green, and blue values can vary while still matching:\r\n\r\n >>> import pyscreeze\r\n >>> pyscreeze.pixelMatchesColor(100, 200, (130, 135, 144))\r\n True\r\n >>> pyscreeze.pixelMatchesColor(100, 200, (140, 125, 134))\r\n False\r\n >>> pyscreeze.pixelMatchesColor(100, 200, (140, 125, 134), tolerance=10)\r\n True\r\n\r\nSupport\r\n-------\r\n\r\nIf you find this project helpful and would like to support its development, [consider donating to its creator on Patreon](https://www.patreon.com/AlSweigart).\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A simple, cross-platform screenshot module for Python 2 and 3.",
"version": "1.0.1",
"project_urls": {
"Homepage": "https://github.com/asweigart/pyscreeze"
},
"split_keywords": [
"screenshot",
"screen",
"screencap",
"capture",
"scrot",
"screencapture",
"image"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "eef0cb456ac4f1a73723d5b866933b7986f02bacea27516629c00f8e7da94c2d",
"md5": "bdf395e46d7de4918323742b856cb7d7",
"sha256": "cf1662710f1b46aa5ff229ee23f367da9e20af4a78e6e365bee973cad0ead4be"
},
"downloads": -1,
"filename": "pyscreeze-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "bdf395e46d7de4918323742b856cb7d7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 27826,
"upload_time": "2024-08-20T23:03:07",
"upload_time_iso_8601": "2024-08-20T23:03:07.291805Z",
"url": "https://files.pythonhosted.org/packages/ee/f0/cb456ac4f1a73723d5b866933b7986f02bacea27516629c00f8e7da94c2d/pyscreeze-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-20 23:03:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "asweigart",
"github_project": "pyscreeze",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pyscreeze"
}
JSON
