### GET /locateOnScreen

Source: https://github.com/asweigart/pyscreeze/blob/master/docs/screenshot.md

Locates an image on the screen with optional grayscale optimization.

```APIDOC
## GET /locateOnScreen

### Description
Locates the first instance of an image on the screen. Using grayscale=True provides a speedup of approximately 30%.

### Method
GET

### Endpoint
locateOnScreen(image, grayscale=False)

### Parameters
#### Query Parameters
- **image** (string) - Required - Path to the image file to locate.
- **grayscale** (boolean) - Optional - If True, converts images to grayscale for faster matching.

### Request Example
pyautogui.locateOnScreen('calc7key.png', grayscale=True)

### Response
#### Success Response (200)
- **location** (tuple) - Returns (left, top, width, height) of the found image.

#### Response Example
(1416, 562, 50, 41)
```

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

### GET /locateAll

Source: https://context7.com/asweigart/pyscreeze/llms.txt

Finds all occurrences of an image within a source image or screen.

```APIDOC
## GET /locateAll

### Description
Finds all occurrences of a needle image within a haystack image or the screen.

### Method
GET

### Endpoint
pyscreeze.locateAll(needle, haystack, confidence=None, limit=None)

### Parameters
#### Query Parameters
- **needle** (str) - Required - Path to the image file to find.
- **haystack** (str) - Optional - Path to the image to search within (defaults to screen).
- **confidence** (float) - Optional - Accuracy threshold (0.0 to 1.0).
- **limit** (int) - Optional - Maximum number of matches to return.

### Request Example
`pyscreeze.locateAll('icon.png', 'screenshot.png', confidence=0.95)`

### Response
#### Success Response (200)
- **matches** (list) - A list of Box objects representing the coordinates of each match.
```

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

### GET /screenshot

Source: https://github.com/asweigart/pyscreeze/blob/master/docs/screenshot.md

Captures a screenshot of the entire screen or a specific region and returns it as an Image object.

```APIDOC
## GET /screenshot

### Description
Captures the current screen content. Optionally saves the output to a file and allows defining a specific region to capture.

### Method
GET

### Endpoint
/screenshot

### Parameters
#### Query Parameters
- **filename** (string) - Optional - Path to save the screenshot file.
- **region** (tuple) - Optional - A four-integer tuple (left, top, width, height) defining the capture area.

### Request Example
{
  "filename": "screenshot.png",
  "region": [0, 0, 300, 400]
}

### Response
#### Success Response (200)
- **image** (object) - The captured Image object.

#### Response Example
{
  "image": "<PIL.Image.Image object>"
}
```

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

### Get Pixel Color (PyAutoGUI)

Source: https://github.com/asweigart/pyscreeze/blob/master/docs/screenshot.md

Shows how to retrieve the RGB color of a specific pixel on the screen. This can be done by first taking a screenshot and then using the Image object's getpixel() method, or more directly using the pyautogui.pixel() function. Both methods take X and Y coordinates as input and return an RGB tuple.

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

```python
import pyautogui
print(pyautogui.pixel(100, 200))
```

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

### Locate Images on Screen with PyScreeze

Source: https://github.com/asweigart/pyscreeze/blob/master/README.md

Finds the coordinates of an image on the screen. Functions like `locateOnScreen` and `locateCenterOnScreen` return the location of the first found instance of a given image file. If the image is not found, `None` is returned. The optional `grayscale` argument can improve performance. For faster searching, installing the OpenCV library is recommended.

```python
import pyscreeze, pyautogui
button7location = pyscreeze.locateOnScreen('calc7key.png')
button7x, button7y = pyscreeze.center(button7location)
pyautogui.click(button7x, button7y)
x, y = pyscreeze.locateCenterOnScreen('calc7key.png')
pyautogui.click(x, y)
```

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

### GET /locateOnScreen

Source: https://github.com/asweigart/pyscreeze/blob/master/docs/screenshot.md

Locates the first occurrence of an image on the screen and returns its coordinates.

```APIDOC
## GET /locateOnScreen

### Description
Searches the screen for the first instance of a provided image file and returns its bounding box coordinates.

### Method
GET

### Endpoint
/locateOnScreen

### Parameters
#### Query Parameters
- **image** (string) - Required - Path to the image file to search for.
- **grayscale** (boolean) - Optional - If true, performs the search in grayscale.

### Request Example
{
  "image": "button.png",
  "grayscale": false
}

### Response
#### Success Response (200)
- **coordinates** (tuple) - (left, top, width, height) of the found instance or null if not found.

#### Response Example
{
  "coordinates": [1416, 562, 50, 41]
}
```

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

### Get Pixel Color - PyScreeze

Source: https://github.com/asweigart/pyscreeze/blob/master/README.md

Shows how to get the RGB color of a specific pixel on the screen. This can be done by taking a screenshot and using the Image object's `getpixel()` method, or by using the `pyscreeze.pixel()` function directly. Both methods return an RGB tuple.

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

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

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

### Take Screenshots with PyScreeze

Source: https://github.com/asweigart/pyscreeze/blob/master/README.md

Captures a screenshot of the entire screen or a specified region. The screenshot can be saved to a file or returned as a Pillow Image object. Dependencies include Pillow for image handling, with fallback methods available if Pillow is not installed. The optional 'region' argument allows for capturing specific parts of the screen.

```python
import pyscreeze
im1 = pyscreeze.screenshot()
im2 = pyscreeze.screenshot('my_screenshot.png')
im = pyscreeze.screenshot(region=(0,0, 300, 400))
```

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

### GET /center

Source: https://context7.com/asweigart/pyscreeze/llms.txt

Calculates the center point of a given region.

```APIDOC
## GET /center

### Description
Calculates the center point (x, y) of a box region.

### Method
GET

### Endpoint
pyscreeze.center(region)

### Parameters
#### Request Body
- **region** (tuple) - Required - A 4-tuple (left, top, width, height).

### Response
#### Success Response (200)
- **point** (namedtuple) - Returns a Point object with x and y attributes.
```

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

### GET /pixel

Source: https://context7.com/asweigart/pyscreeze/llms.txt

Retrieves the RGB color of a pixel at specific coordinates.

```APIDOC
## GET /pixel

### Description
Returns the RGB color tuple of a pixel at the specified screen coordinates.

### Method
GET

### Endpoint
pyscreeze.pixel(x, y)

### Parameters
#### Query Parameters
- **x** (int) - Required - The x-coordinate.
- **y** (int) - Required - The y-coordinate.

### Response
#### Success Response (200)
- **rgb** (tuple) - An RGB tuple (r, g, b).
```

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

### GET /locateCenterOnScreen

Source: https://github.com/asweigart/pyscreeze/blob/master/docs/screenshot.md

Locates the center coordinates of the first occurrence of an image on the screen.

```APIDOC
## GET /locateCenterOnScreen

### Description
Finds the first occurrence of an image on the screen and returns the X and Y coordinates of its center point.

### Method
GET

### Endpoint
/locateCenterOnScreen

### Parameters
#### Query Parameters
- **image** (string) - Required - Path to the image file to search for.

### Request Example
{
  "image": "button.png"
}

### Response
#### Success Response (200)
- **coordinates** (tuple) - (x, y) coordinates of the center of the image or null if not found.

#### Response Example
{
  "coordinates": [1441, 582]
}
```

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

### GET /pixelMatchesColor

Source: https://github.com/asweigart/pyscreeze/blob/master/docs/screenshot.md

Verifies if a specific pixel on the screen matches a target RGB color.

```APIDOC
## GET /pixelMatchesColor

### Description
Checks if the pixel at the given coordinates matches the specified RGB color, with an optional tolerance for color variation.

### Method
GET

### Endpoint
pixelMatchesColor(x, y, expectedRGB, tolerance=0)

### Parameters
#### Query Parameters
- **x** (integer) - Required - X coordinate of the pixel.
- **y** (integer) - Required - Y coordinate of the pixel.
- **expectedRGB** (tuple) - Required - The (R, G, B) tuple to compare against.
- **tolerance** (integer) - Optional - Allowed variation for each RGB channel.

### Request Example
pyautogui.pixelMatchesColor(100, 200, (130, 135, 144), tolerance=10)

### Response
#### Success Response (200)
- **match** (boolean) - Returns True if the pixel matches, False otherwise.

#### Response Example
True
```

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

### Configuration Options

Source: https://context7.com/asweigart/pyscreeze/llms.txt

This section details how to configure PyScreeze's behavior, including exception handling and grayscale matching.

```APIDOC
## Configuration Options

### Description
PyScreeze offers module-level settings to customize its behavior, such as controlling exception handling for image not found scenarios, setting default grayscale matching, and checking for OpenCV integration.

### Method
Module-level variable assignments

### Endpoint
N/A (Local configuration)

### Parameters
#### `pyscreeze.USE_IMAGE_NOT_FOUND_EXCEPTION`
- **(boolean)** - Optional - When `True` (default in 1.0.0), raises `ImageNotFoundException` if an image is not found. When `False`, returns `None` instead.

#### `pyscreeze.GRAYSCALE_DEFAULT`
- **(boolean)** - Optional - If `True`, all `locate` calls will use grayscale matching by default. Defaults to `False`.

### Request Example
```python
import pyscreeze

# Enable exception for not found images (default behavior)
pyscreeze.USE_IMAGE_NOT_FOUND_EXCEPTION = True
try:
    pyscreeze.locateOnScreen('nonexistent.png')
except pyscreeze.ImageNotFoundException:
    print("Image not found on screen")

# Disable exception for not found images (legacy behavior)
pyscreeze.USE_IMAGE_NOT_FOUND_EXCEPTION = False
location = pyscreeze.locateOnScreen('nonexistent.png')
if location is None:
    print("Image not found")

# Enable default grayscale matching
pyscreeze.GRAYSCALE_DEFAULT = True

# Check if OpenCV is being used
print(f"Using OpenCV: {pyscreeze._useOpenCV}")
```

### Response
N/A (Configuration changes affect subsequent function calls)

#### Response Example
N/A
```

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

### Locate Image with Grayscale Option (PyAutoGUI)

Source: https://github.com/asweigart/pyscreeze/blob/master/docs/screenshot.md

Demonstrates how to use pyautogui.locateOnScreen with the grayscale=True option. This can speed up image location by desaturating colors, but may increase the chance of false positives. It takes a screenshot file name as input and returns the location coordinates if found.

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

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

### Capture Screenshots with PyAutoGUI

Source: https://github.com/asweigart/pyscreeze/blob/master/docs/screenshot.md

Demonstrates how to capture the entire screen or a specific region and save it to a file. Requires the Pillow module for image processing.

```python
import pyautogui
im1 = pyautogui.screenshot()
im2 = pyautogui.screenshot('my_screenshot.png')
im = pyautogui.screenshot(region=(0,0, 300, 400))
```

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

### Configure PyScreeze Exception Handling and Grayscale

Source: https://context7.com/asweigart/pyscreeze/llms.txt

This snippet shows how to configure PyScreeze's module-level settings. It demonstrates controlling the behavior of `ImageNotFoundException` (raising an exception or returning None) and setting the default for grayscale matching. It also checks for OpenCV integration.

```python
import pyscreeze

# Control ImageNotFoundException behavior
# When True (default in 1.0.0), raises exception if image not found
# When False, returns None instead
pyscreeze.USE_IMAGE_NOT_FOUND_EXCEPTION = True

try:
    location = pyscreeze.locateOnScreen('nonexistent.png')
except pyscreeze.ImageNotFoundException:
    print("Image not found on screen")

# Set to False for legacy behavior (returns None)
pyscreeze.USE_IMAGE_NOT_FOUND_EXCEPTION = False
location = pyscreeze.locateOnScreen('nonexistent.png')
if location is None:
    print("Image not found")

# Control default grayscale matching
pyscreeze.GRAYSCALE_DEFAULT = True  # All locate calls use grayscale by default

# Check if OpenCV is being used (faster matching)
print(f"Using OpenCV: {pyscreeze._useOpenCV}")
```

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

### Locate Image on Screen with Grayscale - PyScreeze

Source: https://github.com/asweigart/pyscreeze/blob/master/README.md

Demonstrates how to locate an image file on the screen using PyScreeze. The `grayscale=True` option can be used for a potential speedup by desaturating colors, though it might increase false positives. It returns the coordinates of the found image.

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

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

### Locate Multiple Image Matches

Source: https://context7.com/asweigart/pyscreeze/llms.txt

Demonstrates how to find all occurrences of an image on screen. Supports optional confidence thresholds and result limits.

```python
import pyscreeze

# Find all matches in an image file
matches = list(pyscreeze.locateAll('icon.png', 'screenshot.png'))
print(f"Found {len(matches)} matches")

# Iterate through matches
for match in pyscreeze.locateAll('bullet.png', 'document.png'):
    center = pyscreeze.center(match)
    print(f"Match center: ({center.x}, {center.y})")

# With confidence threshold and limit
for match in pyscreeze.locateAll('item.png', 'inventory.png', confidence=0.95, limit=10):
    print(f"Found: {match}")
```

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

### Visualize Image Location on Screen with PyScreeze

Source: https://context7.com/asweigart/pyscreeze/llms.txt

This snippet demonstrates how to locate an image on the screen using PyScreeze and then visualize the found region by drawing an outline around it. It handles cases where the image might not be found. Dependencies include PyScreeze and potentially Pillow for image handling.

```python
import pyscreeze

# Locate the image on the screen
location = pyscreeze.locateOnScreen('button.png')

# If the image was found, visualize its location
if location:
    pyscreeze.showRegionOnScreen(location, outlineColor='green',
                                  filename='found_button.png')
else:
    print("Image not found on screen.")
```

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

### Locate and Visualize Image on Screen

Source: https://context7.com/asweigart/pyscreeze/llms.txt

This snippet demonstrates how to locate an image on the screen using PyScreeze and visualize the found region.

```APIDOC
## Locate and Visualize Image on Screen

### Description
Locates a given image file on the screen and optionally visualizes the found region with an outline and saves it to a file.

### Method
`pyscreeze.locateOnScreen()` and `pyscreeze.showRegionOnScreen()`

### Endpoint
N/A (Local function calls)

### Parameters
#### `locateOnScreen` Parameters
- **image** (str or PIL.Image.Image) - Required - The image file path or PIL Image object to search for.

#### `showRegionOnScreen` Parameters
- **region** (tuple) - Required - The region (left, top, width, height) to highlight.
- **outlineColor** (str) - Optional - The color of the outline (e.g., 'red', 'green').
- **filename** (str) - Optional - If provided, saves the highlighted region to this file.

### Request Example
```python
import pyscreeze

location = pyscreeze.locateOnScreen('button.png')
if location:
    pyscreeze.showRegionOnScreen(location, outlineColor='green',
                                  filename='found_button.png')
```

### Response
#### Success Response (locateOnScreen)
- **location** (Box) - A Box namedtuple representing the region where the image was found (left, top, width, height), or None if not found and `USE_IMAGE_NOT_FOUND_EXCEPTION` is False.

#### Success Response (showRegionOnScreen)
None (function performs side effects)

#### Response Example (locateOnScreen)
```json
{
  "left": 100,
  "top": 200,
  "width": 50,
  "height": 25
}
```
```

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

### Locate and Click Images on Screen

Source: https://github.com/asweigart/pyscreeze/blob/master/docs/screenshot.md

Shows how to find the coordinates of an image on the screen and perform a click action at its center. This is useful for interacting with UI elements that change position.

```python
import pyautogui
button7location = pyautogui.locateOnScreen('calc7key.png')
button7x, button7y = pyautogui.center(button7location)
pyautogui.click(button7x, button7y)

# Or using the shorthand method
x, y = pyautogui.locateCenterOnScreen('calc7key.png')
pyautogui.click(x, y)
```

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

### Locate Multiple Instances of an Image

Source: https://github.com/asweigart/pyscreeze/blob/master/docs/screenshot.md

Demonstrates how to find all occurrences of a specific image on the screen using locateAllOnScreen, which returns a generator of coordinates.

```python
import pyautogui
for pos in pyautogui.locateAllOnScreen('someButton.png'):
    print(pos)

locations = list(pyautogui.locateAllOnScreen('someButton.png'))
```

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

### screenshot()

Source: https://context7.com/asweigart/pyscreeze/llms.txt

Captures the screen or a specific region and returns a Pillow Image object.

```APIDOC
## screenshot

### Description
Takes a screenshot of the entire screen or a specified region and returns a Pillow Image object. Optionally saves the screenshot to a file.

### Method
Function Call

### Parameters
- **imageFilename** (str) - Optional - Path to save the screenshot.
- **region** (tuple) - Optional - (left, top, width, height) to capture.
- **allScreens** (bool) - Optional - Capture all screens on Windows.

### Response
- **Image** (PIL.Image) - The captured screenshot object.
```

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

### locateOnScreen()

Source: https://context7.com/asweigart/pyscreeze/llms.txt

Locates the first occurrence of an image on the screen.

```APIDOC
## locateOnScreen

### Description
Locates the first occurrence of an image on the screen and returns a Box namedtuple with (left, top, width, height) coordinates.

### Parameters
- **image** (str/PIL.Image) - Required - The image to search for.
- **grayscale** (bool) - Optional - Use grayscale for faster matching.
- **region** (tuple) - Optional - Search within a specific (left, top, width, height) region.
- **confidence** (float) - Optional - OpenCV confidence level (0.0 to 1.0).

### Response
- **Box** (namedtuple) - (left, top, width, height) or None if not found.
```

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

### locateCenterOnScreen()

Source: https://context7.com/asweigart/pyscreeze/llms.txt

Finds an image on the screen and returns its center coordinates.

```APIDOC
## locateCenterOnScreen

### Description
Finds an image on the screen and returns the center coordinates as a Point namedtuple (x, y).

### Parameters
- **image** (str/PIL.Image) - Required - The image to search for.
- **grayscale** (bool) - Optional - Use grayscale for faster matching.

### Response
- **Point** (namedtuple) - (x, y) coordinates or None if not found.
```

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

### Utility Functions

Source: https://github.com/asweigart/pyscreeze/blob/master/README.md

Helper functions for image location operations.

```APIDOC
## POST /center

### Description
Calculates the center coordinates (x, y) of a given region.

### Method
POST

### Endpoint
/center

### Parameters
#### Request Body
- **region** (tuple) - Required - A four-integer tuple (left, top, width, height) representing the region.

### Request Example
```json
{
  "region": [1416, 562, 50, 41]
}
```

### Response
#### Success Response (200)
- **coordinates** (tuple) - A two-integer tuple (x, y) representing the center of the region.

#### Response Example
```json
{
  "coordinates": [1441, 582]
}
```
```

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

### Match Pixel Color with Tolerance (PyAutoGUI)

Source: https://github.com/asweigart/pyscreeze/blob/master/docs/screenshot.md

Explains how to check if a pixel at given coordinates matches a specific RGB color, with an optional tolerance level. The pyautogui.pixelMatchesColor() function takes X, Y coordinates, an RGB tuple, and an optional tolerance value. It returns True if the pixel color matches within the specified tolerance, and False otherwise.

```python
import pyautogui
print(pyautogui.pixelMatchesColor(100, 200, (130, 135, 144)))
print(pyautogui.pixelMatchesColor(100, 200, (0, 0, 0)))
```

```python
import pyautogui
print(pyautogui.pixelMatchesColor(100, 200, (140, 125, 134)))
print(pyautogui.pixelMatchesColor(100, 200, (140, 125, 134), tolerance=10))
```

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

### Verify Pixel Color Matches

Source: https://context7.com/asweigart/pyscreeze/llms.txt

Checks if a pixel at given coordinates matches an expected RGB color. Supports fuzzy matching via a tolerance parameter.

```python
import pyscreeze
import time

# Exact color match
matches = pyscreeze.pixelMatchesColor(100, 200, (130, 135, 144))

# Use tolerance for approximate matching
matches = pyscreeze.pixelMatchesColor(100, 200, (140, 125, 134), tolerance=10)

# Practical use: wait for screen element to appear
while not pyscreeze.pixelMatchesColor(800, 600, (0, 255, 0), tolerance=20):
    time.sleep(0.5)
print("Green indicator appeared!")
```

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

### locateAllOnScreen()

Source: https://context7.com/asweigart/pyscreeze/llms.txt

Returns a generator yielding all occurrences of an image on the screen.

```APIDOC
## locateAllOnScreen

### Description
Returns a generator that yields Box namedtuples for all occurrences of an image found on the screen.

### Parameters
- **image** (str/PIL.Image) - Required - The image to search for.
- **grayscale** (bool) - Optional - Use grayscale for faster matching.
- **confidence** (float) - Optional - OpenCV confidence level.

### Response
- **Generator** - Yields Box namedtuples.
```

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

### Visualize Screen Regions

Source: https://context7.com/asweigart/pyscreeze/llms.txt

Debugging tool that captures a screenshot, draws an outline around a specified region, and saves the result to a file.

```python
import pyscreeze

# Highlight a region on screen and save to file
region = (100, 200, 50, 30)
pyscreeze.showRegionOnScreen(region, outlineColor='red', filename='highlighted_region.png')
```

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

### Locate All Occurrences of an Image with PyScreeze

Source: https://github.com/asweigart/pyscreeze/blob/master/README.md

Finds all instances of a given image on the screen or within another image. `locateAllOnScreen` returns a generator yielding tuples of (left, top, width, height) for each match. These results can be iterated over or converted to a list. This is useful for finding multiple buttons or elements on the screen.

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

locations = list(pyscreeze.locateAllOnScreen('someButton.png'))
```

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

### Match Pixel Color - PyScreeze

Source: https://github.com/asweigart/pyscreeze/blob/master/README.md

Explains how to check if a specific pixel on the screen matches a given RGB color. The `pyscreeze.pixelMatchesColor()` function takes X, Y coordinates and an RGB tuple. An optional `tolerance` argument can be provided to allow for slight variations in the color values.

```python
import pyscreeze
print(pyscreeze.pixelMatchesColor(100, 200, (130, 135, 144)))
```

```python
import pyscreeze
print(pyscreeze.pixelMatchesColor(100, 200, (0, 0, 0)))
```

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

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

### Image Location Functions

Source: https://github.com/asweigart/pyscreeze/blob/master/README.md

Functions for locating images on the screen. These functions can return coordinates of the first match or all matches.

```APIDOC
## POST /locateOnScreen

### Description
Locates the first occurrence of a given image (needleImage) on the screen (haystackImage). Returns the coordinates of the found image or None if not found.

### Method
POST

### Endpoint
/locateOnScreen

### Parameters
#### Request Body
- **needleImage** (string) - Required - The filename of the image to search for.
- **grayscale** (boolean) - Optional - If True, performs grayscale matching for faster results. Defaults to False.

### Request Example
```json
{
  "needleImage": "calc7key.png",
  "grayscale": true
}
```

### Response
#### Success Response (200)
- **location** (tuple) - A four-integer tuple (left, top, width, height) of the found image's location, or None if not found.

#### Response Example
```json
{
  "location": [1416, 562, 50, 41]
}
```
```

```APIDOC
## POST /locateCenterOnScreen

### Description
Locates the center coordinates of the first occurrence of a given image on the screen. Returns the (x, y) coordinates or None if not found.

### Method
POST

### Endpoint
/locateCenterOnScreen

### Parameters
#### Request Body
- **needleImage** (string) - Required - The filename of the image to search for.
- **grayscale** (boolean) - Optional - If True, performs grayscale matching. Defaults to False.

### Request Example
```json
{
  "needleImage": "calc7key.png",
  "grayscale": false
}
```

### Response
#### Success Response (200)
- **coordinates** (tuple) - A two-integer tuple (x, y) of the center of the found image, or None if not found.

#### Response Example
```json
{
  "coordinates": [1441, 582]
}
```
```

```APIDOC
## POST /locateAllOnScreen

### Description
Finds all occurrences of a given image on the screen and returns them as a generator yielding (left, top, width, height) tuples.

### Method
POST

### Endpoint
/locateAllOnScreen

### Parameters
#### Request Body
- **needleImage** (string) - Required - The filename of the image to search for.
- **grayscale** (boolean) - Optional - If True, performs grayscale matching. Defaults to False.

### Request Example
```json
{
  "needleImage": "someButton.png",
  "grayscale": true
}
```

### Response
#### Success Response (200)
- **locations** (list of tuples) - A list of (left, top, width, height) tuples for each found instance of the image.

#### Response Example
```json
{
  "locations": [
    [1101, 252, 50, 50],
    [59, 481, 50, 50],
    [1395, 640, 50, 50],
    [1838, 676, 50, 50]
  ]
}
```
```

```APIDOC
## POST /locate

### Description
Locates the first occurrence of a needle image within a haystack image. Returns the coordinates or None if not found.

### Method
POST

### Endpoint
/locate

### Parameters
#### Request Body
- **needleImage** (string) - Required - The filename of the image to search for.
- **haystackImage** (string) - Required - The filename of the image to search within.
- **grayscale** (boolean) - Optional - If True, performs grayscale matching. Defaults to False.

### Request Example
```json
{
  "needleImage": "small_icon.png",
  "haystackImage": "full_screen.png",
  "grayscale": false
}
```

### Response
#### Success Response (200)
- **location** (tuple) - A four-integer tuple (left, top, width, height) of the found image's location, or None if not found.

#### Response Example
```json
{
  "location": [100, 200, 30, 30]
}
```
```

```APIDOC
## POST /locateAll

### Description
Finds all occurrences of a needle image within a haystack image. Returns a generator yielding (left, top, width, height) tuples for each match.

### Method
POST

### Endpoint
/locateAll

### Parameters
#### Request Body
- **needleImage** (string) - Required - The filename of the image to search for.
- **haystackImage** (string) - Required - The filename of the image to search within.
- **grayscale** (boolean) - Optional - If True, performs grayscale matching. Defaults to False.

### Request Example
```json
{
  "needleImage": "button.png",
  "haystackImage": "page_layout.png",
  "grayscale": true
}
```

### Response
#### Success Response (200)
- **locations** (list of tuples) - A list of (left, top, width, height) tuples for each found instance of the image.

#### Response Example
```json
{
  "locations": [
    [50, 100, 40, 40],
    [250, 300, 40, 40]
  ]
}
```
```

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

### Take Screenshot with PyScreeze

Source: https://context7.com/asweigart/pyscreeze/llms.txt

Captures screenshots of the entire screen or a specified region. The captured image is returned as a Pillow Image object and can optionally be saved to a file. Supports capturing all screens on Windows.

```python
import pyscreeze

# Take a full-screen screenshot
im = pyscreeze.screenshot()

# Take a screenshot and save to file
im = pyscreeze.screenshot('my_screenshot.png')

# Capture only a specific region (left, top, width, height)
im = pyscreeze.screenshot(region=(0, 0, 300, 400))

# On Windows, capture all screens
im = pyscreeze.screenshot(allScreens=True)

# Access pixel data from the screenshot
print(im.size)        # Output: (1920, 1080)
print(im.mode)        # Output: 'RGB'
im.save('output.png') # Save manually
```

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

### Screenshot Functions

Source: https://github.com/asweigart/pyscreeze/blob/master/README.md

Functions for capturing screenshots of the entire screen or specific regions.

```APIDOC
## POST /screenshot

### Description
Captures a screenshot of the entire screen or a specified region. The screenshot can be saved to a file or returned as a Pillow Image object.

### Method
POST

### Endpoint
/screenshot

### Parameters
#### Query Parameters
- **region** (tuple) - Optional - A four-integer tuple (left, top, width, height) specifying the region to capture.
- **filename** (string) - Optional - The filename to save the screenshot to.

### Request Example
```json
{
  "region": [0, 0, 300, 400],
  "filename": "my_screenshot.png"
}
```

### Response
#### Success Response (200)
- **image** (Image object) - The captured screenshot as a Pillow Image object.
- **filename** (string) - The path to the saved screenshot file if a filename was provided.

#### Response Example
```json
{
  "image": "<Pillow Image object>",
  "filename": "my_screenshot.png"
}
```
```

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

### Locate Center of Image on Screen with PyScreeze

Source: https://context7.com/asweigart/pyscreeze/llms.txt

Finds the center coordinates (x, y) of the first occurrence of an image on the screen. This is commonly used for clicking on found elements. Supports grayscale matching and integration with PyAutoGUI for direct interaction.

```python
import pyscreeze
import pyautogui

# Find the center of an image on screen
center = pyscreeze.locateCenterOnScreen('calc7key.png')
if center:
    print(f"Center at: x={center.x}, y={center.y}")
    # Output: Center at: x=1441, y=582

# With grayscale for faster matching
center = pyscreeze.locateCenterOnScreen('button.png', grayscale=True)

# Combined with PyAutoGUI for clicking
x, y = pyscreeze.locateCenterOnScreen('submit_button.png')
if x and y:
    pyautogui.click(x, y)
```

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

### Locate Image Within Window

Source: https://context7.com/asweigart/pyscreeze/llms.txt

Restricts image search to a specific window by title. Requires PyGetWindow and automatically focuses the window.

```python
import pyscreeze

# Find image within a specific window
location = pyscreeze.locateOnWindow('save_button.png', 'Notepad')
if location:
    print(f"Found in Notepad at: {location}")

# With additional options
location = pyscreeze.locateOnWindow('icon.png', 'Calculator', grayscale=True, confidence=0.9)
```

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

### locate()

Source: https://context7.com/asweigart/pyscreeze/llms.txt

Finds the first occurrence of a needle image within a haystack image.

```APIDOC
## locate

### Description
Finds the first occurrence of a needle image within a haystack image (not on screen).

### Parameters
- **needle** (str/PIL.Image) - Required - The image to search for.
- **haystack** (str/PIL.Image) - Required - The image to search within.
- **grayscale** (bool) - Optional - Use grayscale for faster matching.
- **confidence** (float) - Optional - OpenCV confidence level.

### Response
- **Box** (namedtuple) - (left, top, width, height) or None if not found.
```

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

### Analyze Pixel Colors

Source: https://context7.com/asweigart/pyscreeze/llms.txt

Retrieves the RGB color tuple of a pixel at specific screen coordinates. Provides high-performance access on Windows systems.

```python
import pyscreeze

# Get pixel color at coordinates
color = pyscreeze.pixel(100, 200)
print(f"RGB: {color}")

# Access individual color components
r, g, b = pyscreeze.pixel(500, 300)
print(f"Red: {r}, Green: {g}, Blue: {b}")

# Check multiple pixels
pixels_to_check = [(100, 100), (200, 200), (300, 300)]
for x, y in pixels_to_check:
    color = pyscreeze.pixel(x, y)
    print(f"Pixel at ({x}, {y}): RGB{color}")
```

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

### Locate All Image Occurrences on Screen with PyScreeze

Source: https://context7.com/asweigart/pyscreeze/llms.txt

Returns a generator that yields Box namedtuples for all instances of an image found on the screen. Useful for identifying multiple elements. Can be converted to a list and supports grayscale and confidence matching.

```python
import pyscreeze

# Find all instances of an image
for location in pyscreeze.locateAllOnScreen('icon.png'):
    print(f"Found at ({location.left}, {location.top})")
# Output:
# Found at (1101, 252)
# Found at (59, 481)
# Found at (1395, 640)

# Convert generator to list
all_locations = list(pyscreeze.locateAllOnScreen('button.png'))
print(f"Found {len(all_locations)} instances")

# With grayscale and confidence
for loc in pyscreeze.locateAllOnScreen('item.png', grayscale=True, confidence=0.95):
    center = pyscreeze.center(loc)
    print(f"Center: ({center.x}, {center.y})")
```

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

### Locate Image on Screen with PyScreeze

Source: https://context7.com/asweigart/pyscreeze/llms.txt

Finds the first occurrence of a specified image (needle) on the screen (haystack). Returns the coordinates as a Box namedtuple or None if not found. Supports grayscale matching, region searching, and confidence levels with OpenCV.

```python
import pyscreeze

# Find an image on the screen
location = pyscreeze.locateOnScreen('button.png')
if location:
    print(f"Found at: left={location.left}, top={location.top}")
    print(f"Size: {location.width}x{location.height}")
    # Output: Found at: left=1416, top=562
    # Output: Size: 50x41

# Use grayscale matching for ~30% speed improvement
location = pyscreeze.locateOnScreen('button.png', grayscale=True)

# Search within a specific region (left, top, width, height)
location = pyscreeze.locateOnScreen('button.png', region=(0, 0, 500, 500))

# Use OpenCV confidence matching (requires opencv-python)
location = pyscreeze.locateOnScreen('button.png', confidence=0.9)

# Set minimum search time to keep looking
location = pyscreeze.locateOnScreen('button.png', minSearchTime=3)
```

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

### Locate Image within Image with PyScreeze

Source: https://github.com/asweigart/pyscreeze/blob/master/README.md

Searches for a smaller image (needle) within a larger image (haystack). The `locate` function returns the coordinates of the first occurrence, while `locateAll` returns a generator for all occurrences. This functionality is useful for image analysis when the search area is predefined.

```python
import pyscreeze
# Assuming needleImage and haystackImage are loaded image objects or file paths
first_match = pyscreeze.locate(needleImage, haystackImage)
all_matches = pyscreeze.locateAll(needleImage, haystackImage)
```

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

### Locate Center of Nearest Image

Source: https://context7.com/asweigart/pyscreeze/llms.txt

Directly returns the center coordinates of the image occurrence nearest to a specified point, often used for direct interaction.

```python
import pyscreeze
import pyautogui

# Find center of nearest matching image to point (500, 400)
x, y = pyscreeze.locateCenterOnScreenNear('icon.png', 500, 400)

# Combine with PyAutoGUI for clicking
center = pyscreeze.locateCenterOnScreenNear('button.png', pyautogui.position().x, pyautogui.position().y)
if center:
    pyautogui.click(center)
```

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

### Calculate Region Center

Source: https://context7.com/asweigart/pyscreeze/llms.txt

Calculates the center point (x, y) of a box region defined by a 4-tuple or Box namedtuple. Useful for determining click coordinates for detected elements.

```python
import pyscreeze

# Get center of a known region
region = (10, 10, 100, 80)
center_point = pyscreeze.center(region)
print(f"Center: ({center_point.x}, {center_point.y})")

# Use with locate functions
location = pyscreeze.locateOnScreen('button.png')
if location:
    center = pyscreeze.center(location)
    print(f"Click at: ({center.x}, {center.y})")
```

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

### Locate All Image Occurrences within Image with PyScreeze

Source: https://context7.com/asweigart/pyscreeze/llms.txt

Returns a generator yielding all occurrences of a needle image within a haystack image. Supports both file paths and PIL Image objects for haystack and needle.

```python
import pyscreeze
```

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

### Locate Nearest Image Occurrence

Source: https://context7.com/asweigart/pyscreeze/llms.txt

Finds the occurrence of an image closest to a specific coordinate point. Useful for disambiguating between multiple identical UI elements.

```python
import pyscreeze

# Find the checkbox closest to coordinates (500, 400)
nearest = pyscreeze.locateOnScreenNear('checkbox.png', 500, 400)
print(f"Nearest checkbox at: {nearest}")

# Use with center to get click coordinates
center = pyscreeze.center(nearest)
print(f"Click at: ({center.x}, {center.y})")
```

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

### Locate Image within Image with PyScreeze

Source: https://context7.com/asweigart/pyscreeze/llms.txt

Finds the first occurrence of a needle image within a haystack image (not on screen). Returns a Box namedtuple or None. Useful for searching within pre-captured screenshots or image files. Supports grayscale and OpenCV confidence matching.

```python
import pyscreeze
from PIL import Image

# Search for needle image in haystack image
haystack = Image.open('screenshot.png')
needle = Image.open('button.png')

location = pyscreeze.locate(needle, haystack)
if location:
    print(f"Found at: {location}")
    # Output: Box(left=100, top=200, width=50, height=30)

# Using file paths directly
location = pyscreeze.locate('small_icon.png', 'full_screenshot.png')

# With grayscale matching
location = pyscreeze.locate('needle.png', 'haystack.png', grayscale=True)

# With OpenCV confidence (requires opencv-python)
location = pyscreeze.locate('needle.png', 'haystack.png', confidence=0.8)
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.