py2ls 0.2.4.32__py3-none-any.whl → 0.2.4.34__py3-none-any.whl

py2ls/ips.py

@@ -1,6 +1,7 @@
 import numpy as np
 import pandas as pd
-import sys, os
+import sys
+import os
 from IPython.display import display
 from typing import List, Optional, Union
 
@@ -17,13 +18,24 @@ import warnings
 warnings.simplefilter("ignore", category=pd.errors.SettingWithCopyWarning)
 warnings.filterwarnings("ignore", category=pd.errors.PerformanceWarning)
 warnings.filterwarnings("ignore")
-import os
 import shutil
 import logging
 from pathlib import Path
 from datetime import datetime
+import re
+import stat
+import platform
 
-
+# only for backup these scripts
+def backup(
+    src="/Users/macjianfeng/Dropbox/github/python/py2ls/.venv/lib/python3.12/site-packages/py2ls/",
+    tar="/Users/macjianfeng/Dropbox/github/python/py2ls/py2ls/",
+    kind="py",
+    overwrite=True,
+):
+    f = listdir(src, kind)
+    [copy(i, tar, overwrite=overwrite) for i in f.path]
+    print(f"all files are copied from {os.path.basename(src)} to {tar}")
 def run_once_within(duration=60, reverse=False):  # default 60s
     import time
 
@@ -786,13 +798,22 @@ def strcmp(
     return candidates[best_match_index], best_match_index
 
 
-def imgcmp(img: list, method="knn", plot_=True, figsize=[12, 6]):
+def imgcmp(img: list, 
+           method:str ="knn", 
+           thr:float =0.75,
+           detector: str = "sift", 
+           plot_:bool =True, 
+           figsize=[12, 6],
+           grid_size=10,# only for grid detector
+           **kwargs):
     """
     Compare two images using SSIM, Feature Matching (SIFT), or KNN Matching.
 
     Parameters:
-    - img (list): List containing two image file paths [img1, img2].
+    - img (list): List containing two image file paths [img1, img2] or two numpy arrays.
     - method (str): Comparison method ('ssim', 'match', or 'knn').
+    - detector (str): Feature detector ('sift', 'grid', 'pixel').
+    - thr (float): Threshold for filtering matches.
     - plot_ (bool): Whether to display the results visually.
     - figsize (list): Size of the figure for plots.
 
@@ -805,8 +826,13 @@ def imgcmp(img: list, method="knn", plot_=True, figsize=[12, 6]):
     from skimage.metrics import structural_similarity as ssim
 
     # Load images
-    image1 = cv2.imread(img[0])
-    image2 = cv2.imread(img[1])
+    if isinstance(img, list) and isinstance(img[0],str):
+        image1 = cv2.imread(img[0])
+        image2 = cv2.imread(img[1])
+        bool_cvt=True
+    else:
+        image1, image2 = np.array(img[0]),np.array(img[1])
+        bool_cvt=False
 
     if image1 is None or image2 is None:
         raise ValueError("Could not load one or both images. Check file paths.")
@@ -841,21 +867,53 @@ def imgcmp(img: list, method="knn", plot_=True, figsize=[12, 6]):
     elif method in ["match", "knn"]:
         # Convert images to grayscale
         gray1 = cv2.cvtColor(image1, cv2.COLOR_BGR2GRAY)
-        gray2 = cv2.cvtColor(image2, cv2.COLOR_BGR2GRAY)
+        gray2 = cv2.cvtColor(image2, cv2.COLOR_BGR2GRAY) 
+
+        if detector == "sift":
+            # SIFT detector
+            sift = cv2.SIFT_create()
+            keypoints1, descriptors1 = sift.detectAndCompute(gray1, None)
+            keypoints2, descriptors2 = sift.detectAndCompute(gray2, None)
+
+        elif detector == "grid":
+            # Grid-based detection
+            keypoints1, descriptors1 = [], []
+            keypoints2, descriptors2 = [], []
+
+            for i in range(0, gray1.shape[0], grid_size):
+                for j in range(0, gray1.shape[1], grid_size):
+                    patch1 = gray1[i:i + grid_size, j:j + grid_size]
+                    patch2 = gray2[i:i + grid_size, j:j + grid_size]
+                    if patch1.size > 0 and patch2.size > 0:
+                        keypoints1.append(cv2.KeyPoint(j + grid_size // 2, i + grid_size // 2, grid_size))
+                        keypoints2.append(cv2.KeyPoint(j + grid_size // 2, i + grid_size // 2, grid_size))
+                        descriptors1.append(np.mean(patch1))
+                        descriptors2.append(np.mean(patch2))
+
+            descriptors1 = np.array(descriptors1).reshape(-1, 1)
+            descriptors2 = np.array(descriptors2).reshape(-1, 1)
+
+        elif detector == "pixel":
+            # Pixel-based direct comparison
+            descriptors1 = gray1.flatten()
+            descriptors2 = gray2.flatten()
+            keypoints1 = [cv2.KeyPoint(x, y, 1) for y in range(gray1.shape[0]) for x in range(gray1.shape[1])]
+            keypoints2 = [cv2.KeyPoint(x, y, 1) for y in range(gray2.shape[0]) for x in range(gray2.shape[1])]
 
-        # Initialize SIFT detector
-        sift = cv2.SIFT_create()
-
-        # Detect and compute features
-        keypoints1, descriptors1 = sift.detectAndCompute(gray1, None)
-        keypoints2, descriptors2 = sift.detectAndCompute(gray2, None)
-
-        if len(keypoints1) == 0 or len(keypoints2) == 0:
-            raise ValueError("No keypoints found in one or both images.")
+        else:
+            raise ValueError("Invalid detector. Use 'sift', 'grid', or 'pixel'.")
+ 
+        # Handle missing descriptors
+        if descriptors1 is None or descriptors2 is None:
+            raise ValueError("Failed to compute descriptors for one or both images.")
+        # Ensure descriptors are in the correct data type
+        if descriptors1.dtype != np.float32:
+            descriptors1 = descriptors1.astype(np.float32)
+        if descriptors2.dtype != np.float32:
+            descriptors2 = descriptors2.astype(np.float32)
 
         # BFMatcher initialization
         bf = cv2.BFMatcher()
-
         if method == "match":  # Cross-check matching
             bf = cv2.BFMatcher(cv2.NORM_L2, crossCheck=True)
             matches = bf.match(descriptors1, descriptors2)
@@ -863,13 +921,14 @@ def imgcmp(img: list, method="knn", plot_=True, figsize=[12, 6]):
 
             # Filter good matches
             good_matches = [
-                m for m in matches if m.distance < 0.75 * matches[-1].distance
+                m for m in matches if m.distance < thr * matches[-1].distance
             ]
 
         elif method == "knn":  # KNN matching with ratio test
+            bf = cv2.BFMatcher()
             matches = bf.knnMatch(descriptors1, descriptors2, k=2)
             # Apply Lowe's ratio test
-            good_matches = [m for m, n in matches if m.distance < 0.75 * n.distance]
+            good_matches = [m for m, n in matches if m.distance < thr * n.distance]
 
         # Calculate similarity score
         similarity_score = len(good_matches) / min(len(keypoints1), len(keypoints2))
@@ -887,23 +946,24 @@ def imgcmp(img: list, method="knn", plot_=True, figsize=[12, 6]):
         dst_pts = np.float32([keypoints2[m.trainIdx].pt for m in good_matches]).reshape(
             -1, 1, 2
         )
-
-        # Calculate Homography using RANSAC
-        homography_matrix, mask = cv2.findHomography(src_pts, dst_pts, cv2.RANSAC, 5.0)
-
         # Apply the homography to image2
-        h, w = image1.shape[:2]
-        warped_image2 = cv2.warpPerspective(image2, homography_matrix, (w, h))
-
-        # Plot result if needed
-        if plot_:
-            fig, ax = plt.subplots(1, 2, figsize=figsize)
-            ax[0].imshow(cv2.cvtColor(image1, cv2.COLOR_BGR2RGB))
-            ax[0].set_title("Image 1")
-            ax[1].imshow(cv2.cvtColor(warped_image2, cv2.COLOR_BGR2RGB))
-            ax[1].set_title("Warped Image 2")
-            plt.tight_layout()
-            plt.show()
+        try:
+            # Calculate Homography using RANSAC
+            homography_matrix, mask = cv2.findHomography(src_pts, dst_pts, cv2.RANSAC, 5.0)
+            h, w = image1.shape[:2]
+            warped_image2 = cv2.warpPerspective(image2, homography_matrix, (w, h))
+
+            # Plot result if needed
+            if plot_:
+                fig, ax = plt.subplots(1, 2, figsize=figsize)
+                ax[0].imshow(cv2.cvtColor(image1, cv2.COLOR_BGR2RGB)) if bool_cvt else ax[0].imshow(image1)
+                ax[0].set_title("Image 1")
+                ax[1].imshow(cv2.cvtColor(warped_image2, cv2.COLOR_BGR2RGB)) if bool_cvt else ax[1].imshow(warped_image2)
+                ax[1].set_title("Warped Image 2")
+                plt.tight_layout()
+                plt.show()
+        except Exception as e:
+            print(e)
 
         # Plot matches if needed
         if plot_:
@@ -911,28 +971,41 @@ def imgcmp(img: list, method="knn", plot_=True, figsize=[12, 6]):
                 image1, keypoints1, image2, keypoints2, good_matches, None, flags=2
             )
             plt.figure(figsize=figsize)
-            plt.imshow(cv2.cvtColor(result, cv2.COLOR_BGR2RGB))
-            plt.title(
-                f"Feature Matches ({len(good_matches)} matches, Score: {similarity_score:.4f})"
-            )
+            plt.imshow(cv2.cvtColor(result, cv2.COLOR_BGR2RGB)) if bool_cvt else plt.imshow(result)
+            plt.title(f"Feature Matches ({len(good_matches)} matches, Score: {similarity_score:.4f})")
             plt.axis("off")
             plt.show()
         # Identify unmatched keypoints
         matched_idx1 = [m.queryIdx for m in good_matches]
         matched_idx2 = [m.trainIdx for m in good_matches]
-
+        matched_kp1 = [kp for i, kp in enumerate(keypoints1) if i in matched_idx1]
+        matched_kp2 = [kp for i, kp in enumerate(keypoints2) if i in matched_idx2]
         unmatched_kp1 = [kp for i, kp in enumerate(keypoints1) if i not in matched_idx1]
         unmatched_kp2 = [kp for i, kp in enumerate(keypoints2) if i not in matched_idx2]
 
-        # Mark unmatched keypoints on the images
-        img1_marked = cv2.drawKeypoints(
+        # Mark keypoints on the images
+        img1_match = cv2.drawKeypoints(
+            image1,
+            matched_kp1,
+            None,
+            color=(0, 0, 255),
+            flags=cv2.DRAW_MATCHES_FLAGS_DRAW_RICH_KEYPOINTS,
+        )
+        img2_match = cv2.drawKeypoints(
+            image2,
+            matched_kp2,
+            None,
+            color=(0, 0, 255),
+            flags=cv2.DRAW_MATCHES_FLAGS_DRAW_RICH_KEYPOINTS,
+        )
+        img1_unmatch = cv2.drawKeypoints(
             image1,
             unmatched_kp1,
             None,
             color=(0, 0, 255),
             flags=cv2.DRAW_MATCHES_FLAGS_DRAW_RICH_KEYPOINTS,
         )
-        img2_marked = cv2.drawKeypoints(
+        img2_unmatch = cv2.drawKeypoints(
             image2,
             unmatched_kp2,
             None,
@@ -940,16 +1013,27 @@ def imgcmp(img: list, method="knn", plot_=True, figsize=[12, 6]):
             flags=cv2.DRAW_MATCHES_FLAGS_DRAW_RICH_KEYPOINTS,
         )
 
-        # Display results
         if plot_:
             fig, ax = plt.subplots(1, 2, figsize=figsize)
-            ax[0].imshow(cv2.cvtColor(img1_marked, cv2.COLOR_BGR2RGB))
+            ax[0].imshow(cv2.cvtColor(img1_unmatch, cv2.COLOR_BGR2RGB)) if bool_cvt else ax[0].imshow(img1_unmatch)
             ax[0].set_title("Unmatched Keypoints (Image 1)")
-            ax[1].imshow(cv2.cvtColor(img2_marked, cv2.COLOR_BGR2RGB))
+            ax[1].imshow(cv2.cvtColor(img2_unmatch, cv2.COLOR_BGR2RGB)) if bool_cvt else ax[1].imshow(img2_unmatch)
             ax[1].set_title("Unmatched Keypoints (Image 2)")
+            ax[0].axis("off")
+            ax[1].axis("off")
             plt.tight_layout()
             plt.show()
-        return good_matches, similarity_score, homography_matrix
+        if plot_:
+            fig, ax = plt.subplots(1, 2, figsize=figsize)
+            ax[0].imshow(cv2.cvtColor(img1_match, cv2.COLOR_BGR2RGB)) if bool_cvt else ax[0].imshow(img1_match)
+            ax[0].set_title("Matched Keypoints (Image 1)")
+            ax[1].imshow(cv2.cvtColor(img2_match, cv2.COLOR_BGR2RGB)) if bool_cvt else ax[1].imshow(img2_match)
+            ax[1].set_title("Matched Keypoints (Image 2)")
+            ax[0].axis("off")
+            ax[1].axis("off")
+            plt.tight_layout()
+            plt.show()
+        return good_matches, similarity_score#, homography_matrix
 
     else:
         raise ValueError("Invalid method. Use 'ssim', 'match', or 'knn'.")
@@ -969,9 +1053,7 @@ def cn2pinyin(
     Args:
         cn_str (str): Chinese string to convert.
         sep (str): Separator for the output Pinyin string.
-        style (Style): "normal","tone", "tone2","tone3",
-        "finals","finals_tone","finals_tone2","finals_tone3",
-        "initials","bopomofo","bopomofo_first","cyrillic","pl",
+        fmt (Style): "normal","tone", "tone2","tone3","finals","finals_tone","finals_tone2","finals_tone3","initials","bopomofo","bopomofo_first","cyrillic","pl",
     Returns:
         cn_str: The Pinyin representation of the Chinese string.
     """
@@ -1224,7 +1306,6 @@ def text2audio(
             print(f"Error opening file: {e}")
     print("done")
 
-
 def str2time(time_str, fmt="24"):
     """
     Convert a time string into the specified format.
@@ -3649,8 +3730,8 @@ def get_os(full=False, verbose=False):
     import os
     import subprocess
     from datetime import datetime, timedelta
-    from collections import defaultdict
 
+    
     def get_os_type():
         os_name = sys.platform
         if "dar" in os_name:
@@ -3663,7 +3744,8 @@ def get_os(full=False, verbose=False):
             else:
                 print(f"{os_name}, returned 'None'")
                 return None
-
+    if not full:
+        return get_os_type()
     def get_os_info():
         """Get the detailed OS name, version, and other platform-specific details."""
 
@@ -4074,11 +4156,6 @@ def get_os(full=False, verbose=False):
     return res
 
 
-import re
-import stat
-import platform
-
-
 def listdir(
     rootdir,
     kind=None,
@@ -4695,57 +4772,64 @@ def is_image(fpath):
     Returns:
         bool: True if the file is a recognized image, False otherwise.
     """
-    import mimetypes
+    from PIL import Image
+    if isinstance(fpath,str):
+        import mimetypes
+
+        # Known image MIME types
+        image_mime_types = {
+            "image/jpeg",
+            "image/png",
+            "image/gif",
+            "image/bmp",
+            "image/webp",
+            "image/tiff",
+            "image/x-icon",
+            "image/svg+xml",
+            "image/heic",
+            "image/heif",
+        }
 
-    # Known image MIME types
-    image_mime_types = {
-        "image/jpeg",
-        "image/png",
-        "image/gif",
-        "image/bmp",
-        "image/webp",
-        "image/tiff",
-        "image/x-icon",
-        "image/svg+xml",
-        "image/heic",
-        "image/heif",
-    }
+        # Known image file extensions
+        image_extensions = {
+            ".jpg",
+            ".jpeg",
+            ".png",
+            ".gif",
+            ".bmp",
+            ".webp",
+            ".tif",
+            ".tiff",
+            ".ico",
+            ".svg",
+            ".heic",
+            ".heif",
+            ".fig",
+            ".jpg",
+        }
 
-    # Known image file extensions
-    image_extensions = {
-        ".jpg",
-        ".jpeg",
-        ".png",
-        ".gif",
-        ".bmp",
-        ".webp",
-        ".tif",
-        ".tiff",
-        ".ico",
-        ".svg",
-        ".heic",
-        ".heif",
-        ".fig",
-        ".jpg",
-    }
+        # Get MIME type using mimetypes
+        mime_type, _ = mimetypes.guess_type(fpath)
 
-    # Get MIME type using mimetypes
-    mime_type, _ = mimetypes.guess_type(fpath)
+        # Check MIME type
+        if mime_type in image_mime_types:
+            return True
 
-    # Check MIME type
-    if mime_type in image_mime_types:
-        return True
+        # Fallback: Check file extension
+        ext = os.path.splitext(fpath)[
+            -1
+        ].lower()  # Get the file extension and ensure lowercase
+        if ext in image_extensions:
+            return True
 
-    # Fallback: Check file extension
-    ext = os.path.splitext(fpath)[
-        -1
-    ].lower()  # Get the file extension and ensure lowercase
-    if ext in image_extensions:
+        return False
+
+    elif isinstance(fpath, Image.Image):
+        # If the input is a PIL Image object
         return True
 
     return False
 
-
 def is_video(fpath):
     """
     Determine if a given file is a video based on MIME type and file extension.
@@ -5055,6 +5139,105 @@ def str2list(str_):
     [l.append(x) for x in str_]
     return l
 
+def str2words(content, method="combined", custom_dict=None, sym_spell_params=None, use_threading=True):
+    """
+    Ultimate text correction function supporting multiple methods,
+    lists or strings, and domain-specific corrections.
+
+    Parameters:
+        content (str or list): Input text or list of strings to correct.
+        method (str): Correction method ('textblob', 'sym', 'combined').
+        custom_dict (dict): Custom dictionary for domain-specific corrections.
+        sym_spell_params (dict): Parameters for initializing SymSpell.
+
+    Returns:
+        str or list: Corrected text or list of corrected strings.
+    """
+    from textblob import TextBlob
+    from symspellpy import SymSpell, Verbosity
+    from functools import lru_cache
+    import pkg_resources
+    from concurrent.futures import ThreadPoolExecutor
+
+    def initialize_symspell(max_edit_distance=2, prefix_length=7):
+        """Initialize SymSpell for advanced spelling correction."""
+        sym_spell = SymSpell(max_edit_distance, prefix_length)
+        dictionary_path = pkg_resources.resource_filename(
+            "symspellpy",
+            # "frequency_bigramdictionary_en_243_342.txt",
+            "frequency_dictionary_en_82_765.txt",
+        )
+
+        sym_spell.load_dictionary(dictionary_path, term_index=0, count_index=1)
+        return sym_spell
+
+    def segment_words(text, sym_spell):
+        """Segment concatenated words into separate words."""
+        segmented = sym_spell.word_segmentation(text)
+        return segmented.corrected_string
+    
+    @lru_cache(maxsize=1000)  # Cache results for repeated corrections
+    def advanced_correction(word, sym_spell):
+        """Correct a single word using SymSpell."""
+        suggestions = sym_spell.lookup(word, Verbosity.CLOSEST, max_edit_distance=2)
+        return suggestions[0].term if suggestions else word
+
+    def apply_custom_corrections(word, custom_dict):
+        """Apply domain-specific corrections using a custom dictionary."""
+        return custom_dict.get(word.lower(), word)
+    def preserve_case(original_word, corrected_word):
+        """
+        Preserve the case of the original word in the corrected word.
+        """
+        if original_word.isupper():
+            return corrected_word.upper()
+        elif original_word[0].isupper():
+            return corrected_word.capitalize()
+        else:
+            return corrected_word.lower()
+    def process_string(text, method, sym_spell=None, custom_dict=None):
+        """
+        Process a single string for spelling corrections.
+        Handles TextBlob, SymSpell, and custom corrections.
+        """
+        if method in ("sym", "combined") and sym_spell:
+            text = segment_words(text, sym_spell)
+
+        if method in ("textblob", "combined"):
+            text = str(TextBlob(text).correct())
+
+        corrected_words = []
+        for word in text.split():
+            original_word = word
+            if method in ("sym", "combined") and sym_spell:
+                word = advanced_correction(word, sym_spell)
+
+            # Step 3: Apply custom corrections
+            if custom_dict:
+                word = apply_custom_corrections(word, custom_dict)
+            # Preserve original case
+            word = preserve_case(original_word, word)
+            corrected_words.append(word)
+
+        return " ".join(corrected_words)
+
+    # Initialize SymSpell if needed
+    sym_spell = None
+    if method in ("sym", "combined"):
+        if not sym_spell_params:
+            sym_spell_params = {"max_edit_distance": 2, "prefix_length": 7}
+        sym_spell = initialize_symspell(**sym_spell_params)
+
+    # Process lists or strings
+    if isinstance(content, list):
+        if use_threading:
+            with ThreadPoolExecutor() as executor:
+                corrected_content = list(executor.map(lambda x: process_string(x, method, sym_spell, custom_dict), content))
+            return corrected_content
+        else:
+            return [process_string(item, method, sym_spell, custom_dict) for item in content]
+    else:
+        return process_string(content, method, sym_spell, custom_dict)
 
 def load_img(fpath):
     """
@@ -5078,7 +5261,7 @@ def load_img(fpath):
         raise OSError(f"Unable to open file '{fpath}' or it is not a valid image file.")
 
 
-def apply_filter(img, *args):
+def apply_filter(img, *args,verbose=True):
     # def apply_filter(img, filter_name, filter_value=None):
     """
     Apply the specified filter to the image.
@@ -5092,7 +5275,7 @@ def apply_filter(img, *args):
     from PIL import ImageFilter
 
     def correct_filter_name(filter_name):
-        if "bl" in filter_name.lower() and "box" not in filter_name.lower():
+        if all(["b" in filter_name.lower(),"ur" in filter_name.lower(), "box" not in filter_name.lower()]):
             return "BLUR"
         elif "cont" in filter_name.lower():
             return "Contour"
@@ -5156,10 +5339,11 @@ def apply_filter(img, *args):
 
     for arg in args:
         if isinstance(arg, str):
-            filter_name = arg
-            filter_name = correct_filter_name(filter_name)
+            filter_name = correct_filter_name(arg)
         else:
             filter_value = arg
+    if verbose:
+        print(f'processing {filter_name}')
     filter_name = filter_name.upper()  # Ensure filter name is uppercase
 
     # Supported filters
@@ -5203,7 +5387,7 @@ def apply_filter(img, *args):
         bands = filter_value if filter_value is not None else None
         return img.filter(supported_filters[filter_name](bands))
     else:
-        if filter_value is not None:
+        if filter_value is not None and verbose:
             print(
                 f"{filter_name} doesn't require a value for {filter_value}, but it remains unaffected"
             )
@@ -5220,6 +5404,8 @@ def detect_angle(image, by="median", template=None):
     import cv2
 
     # Convert to grayscale
+    if np.array(image).shape[-1]>3:
+        image=np.array(image)[:,:,:3]
     gray_image = rgb2gray(image)
 
     # Detect edges using Canny edge detector
@@ -5231,9 +5417,10 @@ def detect_angle(image, by="median", template=None):
     if not lines and any(["me" in by, "pca" in by]):
         print("No lines detected. Adjust the edge detection parameters.")
         return 0
-
+    methods=['mean','median','pca','gradient orientation','template matching','moments','fft']
+    by=strcmp(by, methods)[0]
     # Hough Transform-based angle detection (Median/Mean)
-    if "me" in by:
+    if "me" in by.lower():
         angles = []
         for line in lines:
             (x0, y0), (x1, y1) = line
@@ -5256,7 +5443,7 @@ def detect_angle(image, by="median", template=None):
             return rotation_angle
 
     # PCA-based angle detection
-    elif "pca" in by:
+    elif "pca" in by.lower():
         y, x = np.nonzero(edges)
         if len(x) == 0:
             return 0
@@ -5266,14 +5453,14 @@ def detect_angle(image, by="median", template=None):
         return angle
 
     # Gradient Orientation-based angle detection
-    elif "gra" in by:
+    elif "gra" in by.lower():
         gx, gy = np.gradient(gray_image)
         angles = np.arctan2(gy, gx) * 180 / np.pi
         hist, bin_edges = np.histogram(angles, bins=360, range=(-180, 180))
         return bin_edges[np.argmax(hist)]
 
     # Template Matching-based angle detection
-    elif "temp" in by:
+    elif "temp" in by.lower():
         if template is None:
             # Automatically extract a template from the center of the image
             height, width = gray_image.shape
@@ -5296,7 +5483,7 @@ def detect_angle(image, by="median", template=None):
         return best_angle
 
     # Image Moments-based angle detection
-    elif "mo" in by:
+    elif "mo" in by.lower():
         moments = measure.moments_central(gray_image)
         angle = (
             0.5
@@ -5307,7 +5494,7 @@ def detect_angle(image, by="median", template=None):
         return angle
 
     # Fourier Transform-based angle detection
-    elif "fft" in by:
+    elif "fft" in by.lower():
         f = fft2(gray_image)
         fshift = fftshift(f)
         magnitude_spectrum = np.log(np.abs(fshift) + 1)
@@ -5317,11 +5504,21 @@ def detect_angle(image, by="median", template=None):
         return angle
 
     else:
-        print(f"Unknown method {by}")
+        print(f"Unknown method {by}: supported methods: {methods}")
         return 0
 
 
-def imgsets(img, **kwargs):
+def imgsets(img, 
+            auto:bool=True,
+            size=None,
+            figsize=None,
+            dpi:int=200,
+            show_axis:bool=False,
+            plot_:bool=True,
+            verbose:bool=False,
+            model:str="isnet-general-use",
+            **kwargs,
+            ):
     """
     Apply various enhancements and filters to an image using PIL's ImageEnhance and ImageFilter modules.
 
@@ -5355,6 +5552,9 @@ def imgsets(img, **kwargs):
     Note:
         The "color" and "enhance" enhancements are not implemented in this function.
     """
+
+    import matplotlib.pyplot as plt
+    from PIL import ImageEnhance, ImageOps,Image
     supported_filters = [
         "BLUR",
         "CONTOUR",
@@ -5374,62 +5574,92 @@ def imgsets(img, **kwargs):
         "BOX_BLUR",
         "MEDIAN_FILTER",
     ]
-    print('usage: imgsets(dir_img, contrast="auto", rm=True, color=2.2)')
-    print("\nlog:\n")
-
-    def confirm_rembg_models(model_name):
-        models_support = [
-            "u2net",
-            "u2netp",
-            "u2net_human_seg",
-            "u2net_cloth_seg",
-            "silueta",
-            "isnet-general-use",
-            "isnet-anime",
-            "sam",
-        ]
-        if model_name in models_support:
-            print(f"model_name: {model_name}")
-            return model_name
-        else:
-            print(
-                f"{model_name} cannot be found, check the name:{models_support}, default('isnet-general-use') has been used"
-            )
-            return "isnet-general-use"
+    # *Rembg is a tool to remove images background.
+    # https://github.com/danielgatis/rembg
+    rem_models = {
+        "u2net": "general use cases.",
+        "u2netp": "A lightweight version of u2net model.",
+        "u2net_human_seg": "human segmentation.",
+        "u2net_cloth_seg": "Cloths Parsing from human portrait. Here clothes are parsed into 3 category: Upper body, Lower body and Full body.",
+        "silueta": "Same as u2net but the size is reduced to 43Mb.",
+        "isnet-general-use": "A new pre-trained model for general use cases.",
+        "isnet-anime": "A high-accuracy segmentation for anime character.",
+        "sam": "any use cases.",
+        "birefnet-general": "general use cases.",
+        "birefnet-general-lite": "A light pre-trained model for general use cases.",
+        "birefnet-portrait": "human portraits.",
+        "birefnet-dis": "dichotomous image segmentation (DIS).",
+        "birefnet-hrsod": "high-resolution salient object detection (HRSOD).",
+        "birefnet-cod": "concealed object detection (COD).",
+        "birefnet-massive": "A pre-trained model with massive dataset.",
+    }
+    models_support_rem=list(rem_models.keys())
+
+    str_usage="""
+    imgsets(dir_img, auto=1, color=1.5, plot_=0)
+    imgsets(dir_img, color=2)
+    imgsets(dir_img, pad=(300, 300), bgcolor=(73, 162, 127), plot_=0)
+    imgsets(dir_img, contrast=0, color=1.2, plot_=0)
+    imgsets(get_clip(), flip="tb")# flip top and bottom
+    imgsets(get_clip(), contrast=1, rm=[100, 5, 2]) #'foreground_threshold', 'background_threshold' and 'erode_structure_size'
+    imgsets(dir_img, rm="birefnet-portrait") # with using custom model
+    """
+    if run_once_within():
+        print(str_usage)
 
+    def gamma_correction(image, gamma=1.0, v_max=255):
+        # adjust gama value
+        inv_gamma = 1.0 / gamma
+        lut = [int((i / float(v_max)) ** inv_gamma * int(v_max)) for i in range(int(v_max))]
+        return lut #image.point(lut) 
     def auto_enhance(img):
         """
-        Automatically enhances the image based on its characteristics.
+        Automatically enhances the image based on its characteristics, including brightness,
+        contrast, color range, sharpness, and gamma correction.
+
         Args:
             img (PIL.Image): The input image.
+
         Returns:
-            dict: A dictionary containing the optimal enhancement values.
+            dict: A dictionary containing the optimal enhancement values applied.
+            PIL.Image: The enhanced image.
         """
+        from PIL import Image, ImageEnhance, ImageOps, ImageFilter
+        import numpy as np
         # Determine the bit depth based on the image mode
-        if img.mode in ["1", "L", "P", "RGB", "YCbCr", "LAB", "HSV"]:
-            # 8-bit depth per channel
-            bit_depth = 8
-        elif img.mode in ["RGBA", "CMYK"]:
-            # 8-bit depth per channel + alpha (RGBA) or additional channels (CMYK)
+        try:
+            if img.mode in ["1", "L", "P", "RGB", "YCbCr", "LAB", "HSV"]:
+                bit_depth = 8
+            elif img.mode in ["RGBA", "CMYK"]:
+                bit_depth = 8
+            elif img.mode in ["I", "F"]:
+                bit_depth = 16
+            else:
+                raise ValueError("Unsupported image mode")
+        except:
             bit_depth = 8
-        elif img.mode in ["I", "F"]:
-            # 16-bit depth per channel (integer or floating-point)
-            bit_depth = 16
-        else:
-            raise ValueError("Unsupported image mode")
-        # Calculate the brightness and contrast for each channel
+
+        # Initialize enhancement factors
+        enhancements = {
+            "brightness": 1.0,
+            "contrast": 0,# autocontrasted
+            "color": 1.35,
+            "sharpness": 1.0,
+            "gamma": 1.0
+        }
+
+        # Calculate brightness and contrast for each channel
         num_channels = len(img.getbands())
         brightness_factors = []
         contrast_factors = []
         for channel in range(num_channels):
             channel_histogram = img.split()[channel].histogram()
-            brightness = sum(i * w for i, w in enumerate(channel_histogram)) / sum(
-                channel_histogram
-            )
+            total_pixels = sum(channel_histogram)
+            brightness = sum(i * w for i, w in enumerate(channel_histogram)) / total_pixels
             channel_min, channel_max = img.split()[channel].getextrema()
             contrast = channel_max - channel_min
             # Adjust calculations based on bit depth
-            normalization_factor = 2**bit_depth - 1  # Max value for the given bit depth
+            normalization_factor = 2**bit_depth - 1
             brightness_factor = (
                 1.0 + (brightness - normalization_factor / 2) / normalization_factor
             )
@@ -5438,37 +5668,62 @@ def imgsets(img, **kwargs):
             )
             brightness_factors.append(brightness_factor)
             contrast_factors.append(contrast_factor)
-        # Calculate the average brightness and contrast factors across channels
-        avg_brightness_factor = sum(brightness_factors) / num_channels
-        avg_contrast_factor = sum(contrast_factors) / num_channels
-        return {"brightness": avg_brightness_factor, "contrast": avg_contrast_factor}
 
-    import matplotlib.pyplot as plt
-    from PIL import ImageEnhance, ImageOps
+        # Calculate average brightness and contrast factors across channels
+        enhancements["brightness"] = sum(brightness_factors) / num_channels
+        # Adjust brightness and contrast
+        img = ImageEnhance.Brightness(img).enhance(enhancements["brightness"])
+
+        # # Automatic color enhancement (saturation)
+        # if img.mode == "RGB":
+        #     color_enhancer = ImageEnhance.Color(img)
+        #     color_histogram = np.array(img.histogram()).reshape(3, -1)
+        #     avg_saturation = np.mean([np.std(channel) for channel in color_histogram]) / normalization_factor
+        #     print(avg_saturation)
+        #     enhancements["color"] = min(0, max(0.5, 1.0 + avg_saturation))  # Clamp to a reasonable range
+        #     # img = color_enhancer.enhance(enhancements["color"])
+
+        # Adjust sharpness
+        sharpness_enhancer = ImageEnhance.Sharpness(img)
+        # Use edge detection to estimate sharpness need
+        edges = img.filter(ImageFilter.FIND_EDGES).convert("L")
+        avg_edge_intensity = np.mean(np.array(edges))
+        enhancements["sharpness"] = min(2.0, max(0.5, 1.0 + avg_edge_intensity / normalization_factor))
+        # img = sharpness_enhancer.enhance(enhancements["sharpness"])
+
+        # # Apply gamma correction
+        # def gamma_correction(image, gamma):
+        #     inv_gamma = 1.0 / gamma
+        #     lut = [min(255, max(0, int((i / 255.0) ** inv_gamma * 255))) for i in range(256)]
+        #     return image.point(lut)
+
+        # avg_brightness = np.mean(np.array(img.convert("L"))) / 255
+        # enhancements["gamma"] = min(2.0, max(0.5, 1.0 if avg_brightness > 0.5 else 1.2 - avg_brightness))
+        # img = gamma_correction(img, enhancements["gamma"])
+
+        # Return the enhancements and the enhanced image
+        return enhancements
+
 
     # Load image if input is a file path
     if isinstance(img, str):
         img = load_img(img)
-    img_update = img.copy()
-    # Auto-enhance image if requested
-
-    auto = kwargs.get("auto", False)
-    show = kwargs.get("show", True)
-    show_axis = kwargs.get("show_axis", False)
-    size = kwargs.get("size", None)
-    figsize = kwargs.get("figsize", None)
-    dpi = kwargs.get("dpi", 100)
+    img_update = img.copy() 
 
     if auto:
         kwargs = {**auto_enhance(img_update), **kwargs}
-
+    params=["sharp","color","contrast","bright","crop","rotate",'size',"resize",
+            "thumbnail","cover","contain","filter","fit","pad",
+            "rem","rm","back","bg_color","cut",'gamma','flip']
     for k, value in kwargs.items():
+        k = strcmp(k, params)[0] # correct the param name
         if "shar" in k.lower():
             enhancer = ImageEnhance.Sharpness(img_update)
             img_update = enhancer.enhance(value)
         elif all(
             ["col" in k.lower(), "bg" not in k.lower(), "background" not in k.lower()]
         ):
+            # *color
             enhancer = ImageEnhance.Color(img_update)
             img_update = enhancer.enhance(value)
         elif "contr" in k.lower():
@@ -5476,8 +5731,11 @@ def imgsets(img, **kwargs):
                 enhancer = ImageEnhance.Contrast(img_update)
                 img_update = enhancer.enhance(value)
             else:
-                print("autocontrasted")
-                img_update = ImageOps.autocontrast(img_update)
+                try:
+                    img_update = ImageOps.autocontrast(img_update)
+                    print("autocontrasted")
+                except Exception as e:
+                    print(f"Failed 'autocontrasted':{e}")
         elif "bri" in k.lower():
             enhancer = ImageEnhance.Brightness(img_update)
             img_update = enhancer.enhance(value)
@@ -5488,7 +5746,13 @@ def imgsets(img, **kwargs):
                 value = detect_angle(img_update, by=value)
                 print(f"rotated by {value}°")
             img_update = img_update.rotate(value)
-
+        elif 'flip' in k.lower():
+            if 'l' in value and 'r' in value:
+                # left/right
+                img_update = img_update.transpose(Image.FLIP_LEFT_RIGHT)
+            elif any(['u' in value and'd' in value, 't' in value and 'b' in value]):
+                # up/down or top/bottom
+                img_update = img_update.transpose(Image.FLIP_TOP_BOTTOM)
         elif "si" in k.lower():
             if isinstance(value, tuple):
                 value = list(value)
@@ -5500,36 +5764,44 @@ def imgsets(img, **kwargs):
             img_update = ImageOps.cover(img_update, size=value)
         elif "contain" in k.lower():
             img_update = ImageOps.contain(img_update, size=value)
-        elif "fit" in k.lower():
+        elif "fi" in k.lower() and "t" in k.lower(): # filter
             if isinstance(value, dict):
+                if verbose:
+                    print(f"supported filter: {supported_filters}")
                 for filter_name, filter_value in value.items():
-                    img_update = apply_filter(img_update, filter_name, filter_value)
+                    img_update = apply_filter(img_update, filter_name, filter_value,verbose=verbose)
             else:
                 img_update = ImageOps.fit(img_update, size=value)
         elif "pad" in k.lower():
+            # *ImageOps.pad ensures that the resized image has the exact size specified by the size parameter while maintaining the aspect ratio.
+            # size: A tuple specifying the target size (width, height).
             img_update = ImageOps.pad(img_update, size=value)
         elif "rem" in k.lower() or "rm" in k.lower() or "back" in k.lower():
             from rembg import remove, new_session
-
+            if verbose:
+                preview(rem_models)
+            model=strcmp(model, models_support_rem)[0]
+            session = new_session(model)
             if isinstance(value, bool):
-                session = new_session("isnet-general-use")
                 img_update = remove(img_update, session=session)
             elif value and isinstance(value, (int, float, list)):
-                print("https://github.com/danielgatis/rembg/blob/main/USAGE.md")
+                if verbose:
+                    print("https://github.com/danielgatis/rembg/blob/main/USAGE.md")
+                    print(f"rm=True # using default setting;\nrm=(240,10,10)\n'foreground_threshold'(240) and 'background_threshold' (10) values used to determine foreground and background pixels. \nThe 'erode_structure_size'(10) parameter specifies the size of the erosion structure to be applied to the mask.")
                 if isinstance(value, int):
                     value = [value]
                 if len(value) < 2:
                     img_update = remove(
                         img_update,
                         alpha_matting=True,
-                        alpha_matting_background_threshold=value,
+                        alpha_matting_background_threshold=value, session=session
                     )
                 elif 2 <= len(value) < 3:
                     img_update = remove(
                         img_update,
                         alpha_matting=True,
                         alpha_matting_background_threshold=value[0],
-                        alpha_matting_foreground_threshold=value[1],
+                        alpha_matting_foreground_threshold=value[1], session=session
                     )
                 elif 3 <= len(value) < 4:
                     img_update = remove(
@@ -5537,17 +5809,15 @@ def imgsets(img, **kwargs):
                         alpha_matting=True,
                         alpha_matting_background_threshold=value[0],
                         alpha_matting_foreground_threshold=value[1],
-                        alpha_matting_erode_size=value[2],
+                        alpha_matting_erode_size=value[2], session=session
                     )
             elif isinstance(value, tuple):  # replace the background color
                 if len(value) == 3:
                     value += (255,)
-                img_update = remove(img_update, bgcolor=value)
+                img_update = remove(img_update, bgcolor=value, session=session)
             elif isinstance(value, str):
-                if confirm_rembg_models(value):
-                    img_update = remove(img_update, session=new_session(value))
-                else:
-                    img_update = remove(img_update)
+                # use custom model
+                img_update = remove(img_update, session=new_session(strcmp(value, models_support_rem)[0]))
         elif "bg" in k.lower() and "color" in k.lower():
             from rembg import remove
 
@@ -5557,8 +5827,11 @@ def imgsets(img, **kwargs):
                 if len(value) == 3:
                     value += (255,)
                 img_update = remove(img_update, bgcolor=value)
+        
+        # elif "ga" in k.lower() and "m" in k.lower():
+        #     img_update = gamma_correction(img_update, gamma=value)
     # Display the image if requested
-    if show:
+    if plot_:
         if figsize is None:
             plt.figure(dpi=dpi)
         else:
@@ -9944,13 +10217,17 @@ def get_loc(input_data, user_agent="0413@mygmail.com)", verbose=True):
     # Case 1: Input is a city name (string)
     if isinstance(input_data, str) and not re.match(r"^\d+(\.\d+)?$", input_data):
         location = geolocator.geocode(input_data)
-        if verbose:
-            print(
-                f"Latitude and Longitude for {input_data}: {location.latitude}, {location.longitude}"
-            )
-        else:
-            print(f"Could not find {input_data}.")
-        return location
+        try:
+            if verbose:
+                print(
+                    f"Latitude and Longitude for {input_data}: {location.latitude}, {location.longitude}"
+                )
+            else:
+                print(f"Could not find {input_data}.")
+            return location
+        except Exception as e:
+            print(f'Error: {e}')
+            return
 
     # Case 2: Input is latitude and longitude (float or tuple)
     elif isinstance(input_data, (float, tuple)):
@@ -10144,3 +10421,311 @@ def depass(encrypted_code: str, method: str = "AES", key: str = None):
         raise ValueError("SHA256 is a hash function and cannot be decrypted.")
     else:
         raise ValueError("Unsupported decryption method")
+
+def get_clip(dir_save=None):
+    """
+    Master function to extract content from the clipboard (text, URL, or image).
+
+    Parameters:
+        dir_save (str, optional): If an image is found, save it to this path.
+
+    Returns:
+        dict: A dictionary with extracted content:
+              {
+                  "type": "text" | "url" | "image" | "none",
+                  "content": <str|Image|None>,
+                  "saved_to": <str|None>  # Path if an image is saved
+              }
+    """
+    result = {"type": "none", "content": None, "saved_to": None}
+
+    try:
+        import pyperclip
+        from PIL import ImageGrab, Image
+        import validators
+        # 1. Check for text in the clipboard
+        clipboard_content = pyperclip.paste()
+        if clipboard_content:
+            if validators.url(clipboard_content.strip()):
+                result["type"] = "url"
+                result["content"] = clipboard_content.strip()
+
+            else:
+                result["type"] = "text"
+                result["content"] = clipboard_content.strip()
+            return clipboard_content.strip()
+
+        # 2. Check for image in the clipboard
+        image = ImageGrab.grabclipboard()
+        if isinstance(image, Image.Image):
+            result["type"] = "image"
+            result["content"] = image
+            if dir_save:
+                image.save(dir_save)
+                result["saved_to"] = dir_save
+                print(f"Image saved to {dir_save}.")
+            else:
+                print("Image detected in clipboard but not saved.")
+            return image
+        print("No valid text, URL, or image found in clipboard.")
+        return result
+
+    except Exception as e:
+        print(f"An error occurred: {e}")
+        return result
+
+def keyboard(*args, action='press', n_click=1,interval=0,verbose=False,**kwargs):
+    """
+    Simulates keyboard input using pyautogui.
+
+    Parameters:
+        input_key (str): The key to simulate. Check the list of supported keys with verbose=True.
+        action (str): The action to perform. Options are 'press', 'keyDown', or 'keyUp'.
+        n_click (int): Number of times to press the key (only for 'press' action).
+        interval (float): Time interval between key presses for 'press' action.
+        verbose (bool): Print detailed output, including supported keys and debug info.
+        kwargs: Additional arguments (reserved for future extensions).
+
+    keyboard("command", "d", action="shorcut")
+    """
+    import pyautogui
+    input_key  = args
+
+    actions = ['press','keyDown','keyUp', 'hold','release', 'hotkey','shortcut']
+    action = strcmp(action,actions)[0]
+    keyboard_keys_=['\t', '\n', '\r', ' ', '!', '"', '#', '$', '%', '&', "'", '(',
+                    ')', '*', '+', ',', '-', '.', '/', '0', '1', '2', '3', '4', '5', '6', '7',
+                    '8', '9', ':', ';', '<', '=', '>', '?', '@', '[', '\\', ']', '^', '_', '`',
+                    'a', 'b', 'c', 'd', 'e','f', 'g', 'h', 'i', 'j', 'k', 'l', 'm', 'n', 'o',
+                    'p', 'q', 'r', 's', 't', 'u', 'v', 'w', 'x', 'y', 'z', '{', '|', '}', '~',
+                    'accept', 'add', 'alt', 'altleft', 'altright', 'apps', 'backspace',
+                    'browserback', 'browserfavorites', 'browserforward', 'browserhome',
+                    'browserrefresh', 'browsersearch', 'browserstop', 'capslock', 'clear',
+                    'convert', 'ctrl', 'ctrlleft', 'ctrlright', 'decimal', 'del', 'delete',
+                    'divide', 'down', 'end', 'enter', 'esc', 'escape', 'execute', 'f1', 'f10',
+                    'f11', 'f12', 'f13', 'f14', 'f15', 'f16', 'f17', 'f18', 'f19', 'f2', 'f20',
+                    'f21', 'f22', 'f23', 'f24', 'f3', 'f4', 'f5', 'f6', 'f7', 'f8', 'f9',
+                    'final', 'fn', 'hanguel', 'hangul', 'hanja', 'help', 'home', 'insert', 'junja',
+                    'kana', 'kanji', 'launchapp1', 'launchapp2', 'launchmail',
+                    'launchmediaselect', 'left', 'modechange', 'multiply', 'nexttrack',
+                    'nonconvert', 'num0', 'num1', 'num2', 'num3', 'num4', 'num5', 'num6',
+                    'num7', 'num8', 'num9', 'numlock', 'pagedown', 'pageup', 'pause', 'pgdn',
+                    'pgup', 'playpause', 'prevtrack', 'print', 'printscreen', 'prntscrn',
+                    'prtsc', 'prtscr', 'return', 'right', 'scrolllock', 'select', 'separator',
+                    'shift', 'shiftleft', 'shiftright', 'sleep', 'space', 'stop', 'subtract', 'tab',
+                    'up', 'volumedown', 'volumemute', 'volumeup', 'win', 'winleft', 'winright', 'yen',
+                    'command', 'option', 'optionleft', 'optionright']
+    if verbose:
+        print(f"supported keys: {keyboard_keys_}")
+
+    if action not in ['hotkey','shortcut']:
+        if not isinstance(input_key, list):
+            input_key=list(input_key)
+        input_key = [strcmp(i, keyboard_keys_)[0] for i in input_key ]
+
+    # correct action
+    cmd_keys = ['command', 'option', 'optionleft', 'optionright','win', 'winleft', 'winright','ctrl', 'ctrlleft', 'ctrlright']
+    try:
+        if any([i in cmd_keys for i in input_key]):
+            action='hotkey'
+    except:
+        pass
+
+    print(f"\n{action}: {input_key}")
+    # keyboard
+    if action in ["press"]:
+        # pyautogui.press(input_key, presses=n_click,interval=interval)
+        for _ in range(n_click):
+            for key in input_key:
+                pyautogui.press(key)
+                pyautogui.sleep(interval)
+    elif action in ['keyDown','hold']:
+        # pyautogui.keyDown(input_key)
+        for _ in range(n_click):
+            for key in input_key:
+                pyautogui.keyDown(key)
+                pyautogui.sleep(interval)
+        
+    elif action in ['keyUp','release']:
+        # pyautogui.keyUp(input_key)
+        for _ in range(n_click):
+            for key in input_key:
+                pyautogui.keyUp(key)
+                pyautogui.sleep(interval)
+        
+    elif action in ['hotkey','shortcut']:
+        pyautogui.hotkey(input_key)
+    
+def mouse(
+    *args,  # loc
+    action: str = "move",
+    duration: float = 0.5,
+    loc_type: str = "absolute",  # 'absolute', 'relative'
+    region: tuple = None,  # (tuple, optional): A region (x, y, width, height) to search for the image.
+    image_path: str = None,
+    wait:float = 0,
+    text: str = None,
+    confidence: float = 0.8,
+    button: str = "left",
+    n_click: int = 1,  # number of clicks
+    interval: float = 0.25,  # time between clicks
+    scroll_amount: int = -500,
+    fail_safe: bool = True,
+    grayscale: bool = False,
+    **kwargs,
+):
+    """
+    Master function to handle pyautogui actions.
+
+    Parameters:
+        action (str): The action to perform ('click', 'double_click', 'type', 'drag', 'scroll', 'move', 'locate', etc.).
+        image_path (str, optional): Path to the image for 'locate' or 'click' actions.
+        text (str, optional): Text to type for 'type' action.
+        confidence (float, optional): Confidence level for image recognition (default 0.8).
+        duration (float, optional): Duration for smooth movements in seconds (default 0.5).
+        region (tuple, optional): A region (x, y, width, height) to search for the image.
+        button (str, optional): Mouse button to use ('left', 'right', 'middle').
+        n_click (int, optional): Number of times to click for 'click' actions.
+        interval (float, optional): Interval between clicks for 'click' actions.
+        offset (tuple, optional): Horizontal offset from the located image. y_offset (int, optional): Vertical offset from the located image.
+        scroll_amount (int, optional): Amount to scroll (positive for up, negative for down).
+        fail_safe (bool, optional): Enable/disable pyautogui's fail-safe feature.
+        grayscale (bool, optional): Search for the image in grayscale mode.
+
+    Returns:
+        tuple or None: Returns coordinates for 'locate' actions, otherwise None.
+    """
+    import pyautogui
+    import time
+
+    pyautogui.FAILSAFE = fail_safe  # Enable/disable fail-safe
+    loc_type = "absolute" if "abs" in loc_type else "relative"
+    if len(args) == 1:
+        if isinstance(args[0], str):
+            image_path = args[0]
+            x_offset, y_offset = None, None
+        else:
+            x_offset, y_offset = args
+
+    elif len(args) == 2:
+        x_offset, y_offset = args
+    elif len(args) == 3:
+        x_offset, y_offset, action = args
+    elif len(args) == 4:
+        x_offset, y_offset, action, duration = args
+    else:
+        x_offset, y_offset = None, None
+
+    what_action = [
+        "locate",
+        "click",
+        "double_click",
+        "triple_click",
+        "input",
+        "write",
+        "type",
+        "drag",
+        "move",
+        "scroll",
+        "down",
+        "up",
+        "hold",
+        "press",
+        "release"
+    ]
+    action = strcmp(action, what_action)[0]
+    # get the locations
+    location = None
+    if any([x_offset is None, y_offset is None]):
+        if region is None:
+            w,h=pyautogui.size()
+            region=(0,0,w,h)
+            print(region)
+        try:
+            print(image_path)
+            location = pyautogui.locateOnScreen(
+                image_path, confidence=confidence, region=region, grayscale=grayscale
+            )
+            print(pyautogui.center(location))
+        except Exception as e:
+            location = None
+
+    # try:
+    if location:
+        x, y = pyautogui.center(location)
+        x += x_offset if x_offset else 0
+        y += y_offset if y_offset else 0
+        x_offset, y_offset = x,y
+    print(action)
+    if action in ['locate']:
+        x, y = pyautogui.position()
+    elif action in ["click", "double_click","triple_click"]:
+        # if location:
+        #     x, y = pyautogui.center(location)
+        #     x += x_offset
+        #     y += y_offset
+        #     pyautogui.moveTo(x, y, duration=duration) 
+        #     if action == "click":
+        #         pyautogui.click(x=x, y=y, clicks=n_click, interval=interval, button=button)
+        #     elif action == "double_click":
+        #         pyautogui.doubleClick(x=x, y=y, interval=interval, button=button)
+        #     elif action=='triple_click':
+        #         pyautogui.tripleClick(x=x,y=y,interval=interval,  button=button)
+        # else:
+        if action == "click":
+            pyautogui.moveTo(x_offset, y_offset, duration=duration)
+            time.sleep(wait)
+            pyautogui.click(x=x_offset, y=y_offset, clicks=n_click, interval=interval, button=button)
+        elif action == "double_click":
+            pyautogui.moveTo(x_offset, y_offset, duration=duration)
+            time.sleep(wait)
+            pyautogui.doubleClick(x=x_offset, y=y_offset, interval=interval, button=button)
+        elif action=='triple_click':
+            pyautogui.moveTo(x_offset, y_offset, duration=duration)
+            time.sleep(wait)
+            pyautogui.tripleClick(x=x_offset, y=y_offset, interval=interval, button=button)
+
+    elif action in ["type", "write", "input"]:
+        pyautogui.moveTo(x_offset, y_offset, duration=duration)
+        time.sleep(wait)
+        if text is not None:
+            pyautogui.typewrite(text, interval=interval)
+        else:
+            raise ValueError("Text must be provided for the 'type' action.")
+
+    elif action == "drag":
+        if loc_type == "absolute":
+            pyautogui.dragTo(x_offset, y_offset, duration=duration, button=button)
+        else:
+            pyautogui.dragRel(x_offset, y_offset, duration=duration, button=button)
+
+    elif action in ["move"]:
+        if loc_type == "absolute":
+            pyautogui.moveTo(x_offset, y_offset, duration=duration)
+        else:
+            pyautogui.moveRel(x_offset, y_offset, duration=duration)
+
+    elif action == "scroll":
+        pyautogui.moveTo(x_offset, y_offset, duration=duration)
+        time.sleep(wait)
+        pyautogui.scroll(scroll_amount)
+
+    elif action in ["down",'hold','press']:
+        pyautogui.moveTo(x_offset, y_offset, duration=duration)
+        time.sleep(wait)
+        pyautogui.mouseDown(x_offset, y_offset, button=button, duration=duration)
+
+    elif action in ['up','release']:
+        pyautogui.moveTo(x_offset, y_offset, duration=duration)
+        time.sleep(wait)
+        pyautogui.mouseUp(x_offset, y_offset, button=button, duration=duration)
+
+    else:
+        raise ValueError(f"Unsupported action: {action}")
+
+    # except pyautogui.ImageNotFoundException:
+    #     print(
+    #         "Image not found. Ensure the image is visible and parameters are correct."
+    #     )
+    # except Exception as e:
+    #     print(f"An error occurred: {e}")