# OptimiseWait
A Python utility function for automated image detection and clicking using PyAutoGUI.
## Installation
```bash
# Install from PyPI
pip install optimisewait
# Or install from source
git clone https://github.com/AMAMazing/optimisewait.git
cd optimisewait
pip install .
```
## Quick Start
```python
from optimisewait import optimiseWait, set_autopath, set_altpath
# Set default path for all subsequent optimiseWait calls
set_autopath(r'D:\Images')
# Optional: Set an alternative path for fallback image search
set_altpath(r'D:\Images\Alt')
# Basic usage - wait for image and click
result = optimiseWait('button') # Looks for button.png in D:\Images, then D:\Images\Alt if not found
# Returns {'found': True, 'image': 'button'} if found
```
## Usage Examples
```python
# Override default path for specific call
result = optimiseWait('button', autopath=r'D:\OtherImages')
# Specify both main and alternative paths for specific call
result = optimiseWait('button', autopath=r'D:\Images', altpath=r'D:\Images\Alt')
# Don't wait for image (check if image exists)
result = optimiseWait('button', dontwait=True)
# Returns {'found': False, 'image': None} if not found
# Multiple click options
optimiseWait('button', clicks=2) # Double click
optimiseWait('button', clicks=3) # Triple click
optimiseWait('button', clicks=0) # No click, just wait for image
# Multiple images to search for
result = optimiseWait(['button', 'alt1', 'alt2']) # Will click first image found
# Returns {'found': True, 'image': 'alt1'} if alt1 was found first
# Different clicks per image
optimiseWait(['button', 'alt1', 'alt2'], clicks=[2, 3, 1]) # Different clicks per image
# Offset clicking - single value
optimiseWait('button', xoff=10, yoff=20) # Click 10px right, 20px down from center
# Offset clicking - multiple values for different images
optimiseWait(['button1', 'button2'], xoff=[10, 20], yoff=[5, 15]) # Different offsets per image
optimiseWait(['button1', 'button2', 'button3'], xoff=[10, 20]) # Remaining offsets default to 0
```
## Functions
### set_autopath(path)
Sets the default path for image files that will be used by all subsequent optimiseWait calls.
- `path`: String. Directory path where image files are located.
### set_altpath(path)
Sets the default alternative path for image files. If an image is not found in the main path, it will be searched for in this alternative path.
- `path`: String. Directory path for alternative image files location.
### optimiseWait(filename, ...)
Main function for image detection and clicking.
## Parameters
- `filename`: String or list of strings. Image filename(s) without .png extension
- `dontwait`: Boolean (default False). If True, don't wait for image to appear
- `specreg`: Tuple (default None). Specific region to search in (x, y, width, height)
- `clicks`: Integer or list (default 1). Number of clicks per image (0 = no click, 1 = single, 2 = double, 3 = triple)
- `xoff`: Integer or list (default 0). X offset from center for clicking. Can be different for each image
- `yoff`: Integer or list (default 0). Y offset from center for clicking. Can be different for each image
- `autopath`: String (optional). Directory containing image files. If not provided, uses path set by set_autopath()
- `altpath`: String (optional). Alternative directory for image files. If an image is not found in autopath, it will be searched for here. If not provided, uses path set by set_altpath()
## Return Value
Returns a dictionary with:
- `found`: Boolean indicating if any image was found
- `image`: String name of the found image, or None if no image was found
## Notes
- All image files should be PNG format
- Images are searched with 90% confidence level
- Function will wait indefinitely until image is found (unless dontwait=True)
- When using multiple images, it will try each in order until one is found
- Images are first searched in the main path (autopath), then in the alternative path (altpath) if not found
- If clicks is a single integer, it applies to the first found image (others default to 1 click)
- If clicks is a list shorter than filename list, remaining images default to 1 click
- If xoff/yoff are single integers, same offset applies to all images
- If xoff/yoff are lists shorter than filename list, remaining offsets default to 0
- Click offsets are calculated from the center of the found image
- Default image paths can be set once using set_autopath() and set_altpath() and reused across multiple calls
## Dependencies
- PyAutoGUI >= 0.9.53
## License
MIT License
Raw data
{
"_id": null,
"home_page": "https://github.com/AMAMazing/optimisewait",
"name": "optimisewait",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": null,
"author": "Alex M",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/fa/7f/97a32325afbe177abd8d0bd1d8698f568c595b712ce967f402157432c846/optimisewait-0.3.1.tar.gz",
"platform": null,
"description": "# OptimiseWait\r\n\r\nA Python utility function for automated image detection and clicking using PyAutoGUI.\r\n\r\n## Installation\r\n\r\n```bash\r\n# Install from PyPI\r\npip install optimisewait\r\n\r\n# Or install from source\r\ngit clone https://github.com/AMAMazing/optimisewait.git\r\ncd optimisewait\r\npip install .\r\n```\r\n\r\n## Quick Start\r\n\r\n```python\r\nfrom optimisewait import optimiseWait, set_autopath, set_altpath\r\n\r\n# Set default path for all subsequent optimiseWait calls\r\nset_autopath(r'D:\\Images')\r\n\r\n# Optional: Set an alternative path for fallback image search\r\nset_altpath(r'D:\\Images\\Alt')\r\n\r\n# Basic usage - wait for image and click\r\nresult = optimiseWait('button') # Looks for button.png in D:\\Images, then D:\\Images\\Alt if not found\r\n# Returns {'found': True, 'image': 'button'} if found\r\n```\r\n\r\n## Usage Examples\r\n\r\n```python\r\n# Override default path for specific call\r\nresult = optimiseWait('button', autopath=r'D:\\OtherImages')\r\n\r\n# Specify both main and alternative paths for specific call\r\nresult = optimiseWait('button', autopath=r'D:\\Images', altpath=r'D:\\Images\\Alt')\r\n\r\n# Don't wait for image (check if image exists)\r\nresult = optimiseWait('button', dontwait=True)\r\n# Returns {'found': False, 'image': None} if not found\r\n\r\n# Multiple click options\r\noptimiseWait('button', clicks=2) # Double click\r\noptimiseWait('button', clicks=3) # Triple click\r\noptimiseWait('button', clicks=0) # No click, just wait for image\r\n\r\n# Multiple images to search for\r\nresult = optimiseWait(['button', 'alt1', 'alt2']) # Will click first image found\r\n# Returns {'found': True, 'image': 'alt1'} if alt1 was found first\r\n\r\n# Different clicks per image\r\noptimiseWait(['button', 'alt1', 'alt2'], clicks=[2, 3, 1]) # Different clicks per image\r\n\r\n# Offset clicking - single value\r\noptimiseWait('button', xoff=10, yoff=20) # Click 10px right, 20px down from center\r\n\r\n# Offset clicking - multiple values for different images\r\noptimiseWait(['button1', 'button2'], xoff=[10, 20], yoff=[5, 15]) # Different offsets per image\r\noptimiseWait(['button1', 'button2', 'button3'], xoff=[10, 20]) # Remaining offsets default to 0\r\n```\r\n\r\n## Functions\r\n\r\n### set_autopath(path)\r\nSets the default path for image files that will be used by all subsequent optimiseWait calls.\r\n- `path`: String. Directory path where image files are located.\r\n\r\n### set_altpath(path)\r\nSets the default alternative path for image files. If an image is not found in the main path, it will be searched for in this alternative path.\r\n- `path`: String. Directory path for alternative image files location.\r\n\r\n### optimiseWait(filename, ...)\r\nMain function for image detection and clicking.\r\n\r\n## Parameters\r\n\r\n- `filename`: String or list of strings. Image filename(s) without .png extension\r\n- `dontwait`: Boolean (default False). If True, don't wait for image to appear\r\n- `specreg`: Tuple (default None). Specific region to search in (x, y, width, height)\r\n- `clicks`: Integer or list (default 1). Number of clicks per image (0 = no click, 1 = single, 2 = double, 3 = triple)\r\n- `xoff`: Integer or list (default 0). X offset from center for clicking. Can be different for each image\r\n- `yoff`: Integer or list (default 0). Y offset from center for clicking. Can be different for each image\r\n- `autopath`: String (optional). Directory containing image files. If not provided, uses path set by set_autopath()\r\n- `altpath`: String (optional). Alternative directory for image files. If an image is not found in autopath, it will be searched for here. If not provided, uses path set by set_altpath()\r\n\r\n## Return Value\r\n\r\nReturns a dictionary with:\r\n- `found`: Boolean indicating if any image was found\r\n- `image`: String name of the found image, or None if no image was found\r\n\r\n## Notes\r\n\r\n- All image files should be PNG format\r\n- Images are searched with 90% confidence level\r\n- Function will wait indefinitely until image is found (unless dontwait=True)\r\n- When using multiple images, it will try each in order until one is found\r\n- Images are first searched in the main path (autopath), then in the alternative path (altpath) if not found\r\n- If clicks is a single integer, it applies to the first found image (others default to 1 click)\r\n- If clicks is a list shorter than filename list, remaining images default to 1 click\r\n- If xoff/yoff are single integers, same offset applies to all images\r\n- If xoff/yoff are lists shorter than filename list, remaining offsets default to 0\r\n- Click offsets are calculated from the center of the found image\r\n- Default image paths can be set once using set_autopath() and set_altpath() and reused across multiple calls\r\n\r\n## Dependencies\r\n\r\n- PyAutoGUI >= 0.9.53\r\n\r\n## License\r\n\r\nMIT License\r\n",
"bugtrack_url": null,
"license": null,
"summary": "A Python utility for automated image detection and clicking",
"version": "0.3.1",
"project_urls": {
"Homepage": "https://github.com/AMAMazing/optimisewait"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0f36245ac052fe9afe3ba6c63bacf6def4c6546c2420d7c478338097a5cae807",
"md5": "8b4c70e06ceb0fa87ca6f20bdfb801b9",
"sha256": "6ccf9a8285364eb975c92898be161fd85f799eec50fee5c95f4871183d5b909c"
},
"downloads": -1,
"filename": "optimisewait-0.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8b4c70e06ceb0fa87ca6f20bdfb801b9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 4783,
"upload_time": "2024-12-07T10:06:38",
"upload_time_iso_8601": "2024-12-07T10:06:38.761531Z",
"url": "https://files.pythonhosted.org/packages/0f/36/245ac052fe9afe3ba6c63bacf6def4c6546c2420d7c478338097a5cae807/optimisewait-0.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fa7f97a32325afbe177abd8d0bd1d8698f568c595b712ce967f402157432c846",
"md5": "5386a80c08586f6f89377ff6f511fea9",
"sha256": "679e8ee32792c51960e0fbffd9305ab085736916c2ddc4040a61fbbbfda91d25"
},
"downloads": -1,
"filename": "optimisewait-0.3.1.tar.gz",
"has_sig": false,
"md5_digest": "5386a80c08586f6f89377ff6f511fea9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 4835,
"upload_time": "2024-12-07T10:06:41",
"upload_time_iso_8601": "2024-12-07T10:06:41.687352Z",
"url": "https://files.pythonhosted.org/packages/fa/7f/97a32325afbe177abd8d0bd1d8698f568c595b712ce967f402157432c846/optimisewait-0.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-07 10:06:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "AMAMazing",
"github_project": "optimisewait",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "optimisewait"
}
JSON
