v2.1.0

Author: DedInc

LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2024 Vladislav Zenkevich
+Copyright (c) 2024-2025 Vladislav Zenkevich
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.MD

@@ -1,26 +1,64 @@
 # 🤖 Emunium
 
-A Python module for automating interactions to mimic human behavior in standalone apps or browsers when using Selenium, Pyppeteer, or Playwright. Provides utilities to programmatically move the mouse cursor, click on page elements, type text, and scroll as if performed by a human user.
-
+Emunium is a Python module that helps you automate interactions in a human-like way. It works with standalone applications or browsers when using Selenium, Pyppeteer, or Playwright. Emunium makes the mouse movements, clicks, typing, and scrolling appear more natural, which can help your tests avoid detection.
 
 ![Emunium preview](https://raw.githubusercontent.com/DedInc/emunium/main/preview.gif)
 
+---
 
 ## 🚀 Quickstart (Standalone)
 
+Below is a basic example that shows how to search for an image on your screen, type some text, and click a button. This example uses standalone mode.
+
 ```python
-from emunium import Emunium
+from emunium import Emunium, ClickType
 
+# Create an instance of Emunium
 emunium = Emunium()
 
+# Find a text field on the screen using an image of the field
 elements = emunium.find_elements('field.png', min_confidence=0.8)
 
+# Type into the first found element
 emunium.type_at(elements[0], 'Automating searches')
 
+# Find the search icon using an image and click it
 elements = emunium.find_elements('search_icon.png', min_confidence=0.8)
 emunium.click_at(elements[0])
 ```
 
+---
+
+## 🔍 OCR Text Search (only in Standalone)
+
+Emunium can also search for text on the screen using Optical Character Recognition (OCR). To use this feature, create your Emunium instance with OCR enabled. This uses [EasyOCR](https://github.com/JaidedAI/EasyOCR) under the hood.
+
+### How It Works
+
+The new `find_text_elements()` method scans the screen for text that matches your query. You can adjust the minimum confidence and limit the number of results.
+
+### Example
+
+```python
+from emunium import Emunium
+
+# Create an Emunium instance with OCR enabled.
+emunium = Emunium(ocr=True, use_gpu=True, langs=['en']) # use_gpu is default True, langs is default ['en'], ocr is default False
+
+# Search for text that contains the word "Submit"
+text_elements = emunium.find_text_elements('Submit', min_confidence=0.8) # min_confidence is default 0.8
+
+# If the text is found, click on the first occurrence.
+if text_elements:
+    emunium.click_at(text_elements[0])
+```
+
+*Note:* Make sure you have EasyOCR installed by running `pip install easyocr` before using the OCR feature.
+
+---
+
+Quickstarts for one of more cases. The code below opens DuckDuckGo, types a query, and clicks the search button.
+
 ## 🚀 Quickstart (with Selenium)
 
 ```python
@@ -36,16 +74,19 @@ emunium = EmuniumSelenium(driver)
 
 driver.get('https://duckduckgo.com/')
 
+# Wait for the search field to be clickable and type your query
 element = wait.until(EC.element_to_be_clickable((By.CSS_SELECTOR, '[data-state="suggesting"]')))
-
 emunium.type_at(element, 'Automating searches')
 
+# Find and click the search button
 submit = wait.until(EC.element_to_be_clickable((By.CSS_SELECTOR, '[aria-label="Search"]')))
 emunium.click_at(submit)
 
 driver.quit()
 ```
 
+---
+
 ## 🚀 Quickstart (with Pyppeteer)
 
 ```python
@@ -68,11 +109,14 @@ async def main():
 
     await browser.close()
 
-asyncio.get_event_loop().run_until_complete(main())
+asyncio.run(main())
 ```
 
+---
+
 ## 🚀 Quickstart (with Playwright)
 
+
 ```python
 import asyncio
 from playwright.async_api import async_playwright
@@ -97,63 +141,60 @@ async def main():
 asyncio.run(main())
 ```
 
-## 🖱️ Moving the Mouse
+---
 
-The `move_to()` method moves the mouse cursor smoothly to the provided element with small randomizations in speed and path to seem human.
+## 🖱️ Mouse Movements and Clicks
 
-Options:
-- `offset_x` and `offset_y` - offset mouse position from element center
+Emunium simulates natural mouse movements and clicks:
 
-## 🖱️ Clicking Elements
+- **Moving the Mouse:**
+  The `move_to()` method moves the cursor smoothly to the target position. You can add small random offsets for a more human-like behavior.
 
-The `click_at()` method moves via `move_to()` and clicks at the center of the provided element.
+- **Clicking Elements:**
+  Use `click_at()` to click on an element after moving to it. You can specify the type of click (left, right, middle, or double):
 
-Emunium supports multiple mouse click types:
+  ```python
+  from emunium import ClickType
 
-```python
-from emunium import ClickType
-
-emunium.click_at(element)                   # left click
-emunium.click_at(element, ClickType.RIGHT)  # right click  
-emunium.click_at(element, ClickType.MIDDLE) # middle click
-emunium.click_at(element, ClickType.DOUBLE) # double click
-```
+  emunium.click_at(element)                    # left click
+  emunium.click_at(element, ClickType.RIGHT)   # right click
+  emunium.click_at(element, ClickType.MIDDLE)  # middle click
+  emunium.click_at(element, ClickType.DOUBLE)  # double click
+  ```
 
-## 🔎 Finding Elements
+---
 
-In standalone mode, Emunium can locate elements on the screen using image matching with the `find_elements` method:
+## 🔎 Finding Elements on the Screen (only in Standalone)
 
-```python
-elements = emunium.find_elements('search_icon.png', min_confidence=0.8)
-```
+Emunium uses image matching to find elements:
 
-The `find_elements` method takes the following parameters:
+- **find_elements():**
+  Locate elements on the screen using an image file.
 
-- `image_path` (required): The path to the image file to search for on the screen.
-- `min_confidence` (optional, default 0.8): The minimum confidence level (between 0 and 1) for image matching. Higher values result in more precise matching but may miss some elements.
-- `target_height` (optional): The expected height of the elements to find. If provided along with `target_width`, elements that don't match the specified size (within a tolerance based on `min_confidence`) will be filtered out.
-- `target_width` (optional): The expected width of the elements to find. Must be provided together with `target_height`.
-- `max_elements` (optional, default 0): The maximum number of elements to return. If set to 0 or not provided, all matching elements will be returned.
+  ```python
+  elements = emunium.find_elements('search_icon.png', min_confidence=0.8)
+  ```
 
-The `find_elements` method returns a list of dictionaries, each containing the 'x' and 'y' coordinates of the center point of a matched element.
+  You can also set target sizes and limit the number of elements found.
 
+---
 
 ## ⌨️ Typing Text
 
-The `type_at()` method moves to the provided element via `move_to()`, clicks it via `click_to()`, and types the provided text in a "silent" way, spreading out key presses over time with small randomizations to mimic human typing.
+The `type_at()` method moves to an element, clicks on it, and types text in a "silent" way. This method mimics human typing by spreading out key presses with small, random delays.
 
-Options:
-- `characters_per_minute` - typing speed in characters per minute (default 280)
-- `offset` - randomization (threshold) in milliseconds between key presses (default 20ms)
+Options include:
+- `characters_per_minute`: Typing speed (default is 280 CPM).
+- `offset`: Random delay (default is 20ms).
+
+---
 
 ## 📜 Scrolling Pages
 
-The `scroll_to()` method scrolls the page to bring the provided element into view using smooth scrolling.
+The `scroll_to()` method scrolls smoothly to bring an element into view. It uses timeouts and checks to ensure smooth scrolling even when there are minor hiccups.
 
-Includes timeouts and checks to handle issues with scrolling getting stuck.
+---
 
 ## 🏁 Conclusion
 
-Emunium provides a set of utilities to help automate browser interactions in a more human-like way when using Selenium, Pyppeteer, or Playwright. By moving the mouse, clicking, typing, and scrolling in a less robotic fashion, tests can avoid detection and run more reliably.
-
-While basic automation scripts can still get the job done, Emunium aims to make tests appear even more life-like. Using the randomizations and smooth behaviors it offers can be beneficial for automation projects that require avoiding detections.
+Emunium provides a set of easy-to-use tools for automating user interactions. Whether you need to automate clicks, type text, or even search for text on your screen using OCR, Emunium offers flexible solutions for both browser and standalone applications. Its human-like behavior helps make your tests more robust and less likely to be detected as automation.

emunium/base.py

@@ -12,52 +12,31 @@
     keyboard = None
 
 import pyautogui
-import pyclick
-
+from humancursor import SystemCursor
 from enum import Enum
 
-
-class ClickType(Enum):
-    LEFT = 0
-    RIGHT = 1
-    MIDDLE = 2
-    DOUBLE = 3
-
-
 def get_image_size(file_path):
     with open(file_path, "rb") as file:
         file.seek(16)
         width_bytes = file.read(4)
         height_bytes = file.read(4)
         width = struct.unpack(">I", width_bytes)[0]
         height = struct.unpack(">I", height_bytes)[0]
-        return (
-            width,
-            height,
-        )
+        return (width, height)
 
+class ClickType(Enum):
+    LEFT = 0
+    RIGHT = 1
+    MIDDLE = 2
+    DOUBLE = 3
 
 class EmuniumBase:
     def __init__(self):
-        self.clicker = pyclick.HumanClicker()
-        self._extend_clicker()
+
+        self.cursor = SystemCursor()
         self.browser_offsets = ()
         self.browser_inner_window = ()
 
-    def _extend_clicker(self):
-        def right_click(self):
-            pyautogui.click(button="right")
-
-        def middle_click(self):
-            pyautogui.click(button="middle")
-
-        def double_click(self):
-            pyautogui.doubleClick()
-
-        self.clicker.right_click = right_click.__get__(self.clicker)
-        self.clicker.middle_click = middle_click.__get__(self.clicker)
-        self.clicker.double_click = double_click.__get__(self.clicker)
-
     async def _get_browser_properties_if_not_found(self, screenshot_func):
         if not self.browser_offsets or not self.browser_inner_window:
             with tempfile.NamedTemporaryFile(suffix=".png", delete=False) as temp_file:
@@ -68,83 +47,64 @@ async def _get_browser_properties_if_not_found(self, screenshot_func):
                 screenshot_func(temp_screen_path)
 
             location = pyautogui.locateOnScreen(temp_screen_path, confidence=0.6)
-            self.browser_offsets = (
-                location.left,
-                location.top,
-            )
+            if location is not None:
+                self.browser_offsets = (location.left, location.top)
+            else:
+                self.browser_offsets = (0, 0)
             self.browser_inner_window = get_image_size(temp_screen_path)
             os.remove(temp_screen_path)
 
     def _get_center(self, element_location, element_size):
-        offset_to_screen_x, offset_to_screen_y = self.browser_offsets
+        offset_to_screen_x, offset_to_screen_y = self.browser_offsets if self.browser_offsets else (0, 0)
         element_x = element_location["x"] + offset_to_screen_x
         element_y = element_location["y"] + offset_to_screen_y
-
         centered_x = element_x + (element_size["width"] // 2)
         centered_y = element_y + (element_size["height"] // 2)
-
         return {"x": centered_x, "y": centered_y}
 
-    def _move(
-        self,
-        center,
-        offset_x=random.uniform(0.0, 1.5),
-        offset_y=random.uniform(0.0, 1.5),
-    ):
-        target_x, target_y = round(center["x"] + offset_x), round(
-            center["y"] + offset_y
-        )
+    def _move(self, center, offset_x=None, offset_y=None):
+        if offset_x is None:
+            offset_x = random.uniform(0.0, 1.5)
+        if offset_y is None:
+            offset_y = random.uniform(0.0, 1.5)
+        target_x = round(center["x"] + offset_x)
+        target_y = round(center["y"] + offset_y)
+        self.cursor.move_to([target_x, target_y])
 
-        current_x, current_y = pyautogui.position()
-        distance = math.sqrt((target_x - current_x) ** 2 + (target_y - current_y) ** 2)
-
-        speed = max(
-            random.uniform(0.3, 0.6),
-            min(random.uniform(2.0, 2.5), distance / random.randint(500, 700)),
-        )
-
-        self.clicker.move((target_x, target_y), speed)
-
-    def _click(self, click_type=ClickType.LEFT):
+    def _click(self, coordinate, click_type=ClickType.LEFT, click_duration=0):
         if click_type == ClickType.LEFT:
-            self.clicker.click()
+            self.cursor.click_on(coordinate, click_duration=click_duration)
         elif click_type == ClickType.RIGHT:
-            self.clicker.right_click()
+            pyautogui.click(x=coordinate[0], y=coordinate[1], button="right")
         elif click_type == ClickType.MIDDLE:
-            self.clicker.middle_click()
+            pyautogui.click(x=coordinate[0], y=coordinate[1], button="middle")
         elif click_type == ClickType.DOUBLE:
-            self.clicker.double_click()
 
-    def silent_type(self, text, characters_per_minute=280, offset=20):
-        total_chars = len(text)
-        time_per_char = 60 / characters_per_minute
+            self.cursor.click_on(coordinate)
+            time.sleep(0.1)
+            self.cursor.click_on(coordinate)
 
-        for i, char in enumerate(text):
+    def _silent_type(self, text, characters_per_minute=280, offset=20):
+        time_per_char = 60 / characters_per_minute
+        for char in text:
             randomized_offset = random.uniform(-offset, offset) / 1000
             delay = time_per_char + randomized_offset
-
-            # Update by Pranav (https://github.com/ps428)
-            # keyboard.write used in silent_type needs sudo mode on Linux machines
-            # This uses pyautogui.press instead of keyboard.write
             if keyboard is None:
                 pyautogui.press(char)
             else:
                 keyboard.write(char)
-
             time.sleep(delay)
 
-
     def _scroll_smoothly_to_element(self, element_rect):
-        window_width = self.browser_inner_window[0]
-        window_height = self.browser_inner_window[1]
+        if self.browser_inner_window:
+            window_width, window_height = self.browser_inner_window
+        else:
+            screen_size = pyautogui.size()
+            window_width, window_height = screen_size.width, screen_size.height
 
         scroll_amount = element_rect["y"] - window_height // 2
         scroll_steps = abs(scroll_amount) // 100
-
-        if scroll_amount > 0:
-            scroll_direction = -1
-        else:
-            scroll_direction = 1
+        scroll_direction = -1 if scroll_amount > 0 else 1
 
         for _ in range(scroll_steps):
             pyautogui.scroll(scroll_direction * 100)
@@ -154,3 +114,6 @@ def _scroll_smoothly_to_element(self, element_rect):
         if remaining_scroll != 0:
             pyautogui.scroll(scroll_direction * remaining_scroll)
             time.sleep(random.uniform(0.05, 0.1))
+
+    def drag_and_drop(self, start_coords, end_coords):
+        self.cursor.drag_and_drop(start_coords, end_coords)