Native Linux ARM64 builds (#328)

Avasam · web-flow · commit a8e02499de9b · 2025-06-12T21:53:28.000-04:00
diff --git a/.github/ISSUE_TEMPLATE/bug-or-crash-report.md b/.github/ISSUE_TEMPLATE/bug-or-crash-report.md
@@ -39,6 +39,7 @@ If AutoSplit showed an exception traceback, please paste it here:
 ### Version (please complete the following information)
 
 - OS: [e.g. Windows 10.0.19045]
+- Architecture: [x64 or ARM64]
 - AutoSplit: [e.g. v2.0.0]
 
 ### AutoSplit Profile and Split Images
diff --git a/.github/workflows/lint-and-build.yml b/.github/workflows/lint-and-build.yml
@@ -75,12 +75,13 @@ jobs:
       fail-fast: false
       # Only the Python version we plan on shipping matters.
       matrix:
-        os: [windows-latest, ubuntu-22.04]
+        # OpenCV doesn't support windows-11-arm yet https://github.com/opencv/opencv-python/issues/806
+        os: [windows-latest, ubuntu-22.04, ubuntu-22.04-arm]
         python-version: ["3.13"]
     steps:
       - uses: actions/checkout@v4
-      # region https://github.com/pyinstaller/pyinstaller/issues/9012
-      - name: Set up Python for PyInstaller tk issue
+      # region pyinstaller/pyinstaller#9012 + astral-sh/uv#12906
+      - name: Set up Python for PyInstaller tk and ARM64 issue
         if: ${{ startsWith(matrix.os, 'ubuntu') }}
         uses: actions/setup-python@v5
         with:
diff --git a/README.md b/README.md
@@ -44,9 +44,10 @@ To understand how to use AutoSplit and how it works in-depth, please read the [t
 
 ### Compatibility
 
-- Windows 10 and 11.
+- Windows 10 and 11. (x64 only)
 - Linux (still in early development)
-  - Should work on Ubuntu 20.04+ (Only tested on Ubuntu 22.04)
+  - Both x64 and ARM64 architectures \* (see [Known Limitations](#known-limitations) for ARM64)
+  - Should work on Ubuntu 22.04+
   - Wayland is not currently supported
   - WSL2/WSLg requires an additional Desktop Environment, external X11 server, and/or systemd
 - If you'd like to run the project directly in Python from the source code, refer to the [build instructions](/docs/build%20instructions.md).
@@ -73,6 +74,7 @@ See the [installation instructions](https://github.com/Toufool/LiveSplit.AutoSpl
 - Linux support is incomplete and we're [looking for contributors](../../issues?q=is%3Aissue+is%3Aopen+label%3A"help+wanted"+label%3ALinux+).
   - Incompatible with LiveSplitOne on Linux (see <https://github.com/LiveSplit/LiveSplitOne/issues/1025>)
 - Antivirus false positives. Please read <https://github.com/pyinstaller/pyinstaller/blob/develop/.github/ISSUE_TEMPLATE/antivirus.md>
+- The Perceptual Hash Comparison Method similarity may differ by 3.125% on ARM64. (this will be solved eventually, we have to use a fallback method for now)
 
 ## Resources
 
diff --git a/pyproject.toml b/pyproject.toml
@@ -8,15 +8,19 @@ dependencies = [
   "PyAutoGUI >=0.9.52",
   "PyWinCtl >=0.0.42", # py.typed
   "keyboard @ git+https://github.com/boppreh/keyboard.git", # Fix install on macos and linux-ci https://github.com/boppreh/keyboard/pull/568
-  "numpy >=2.1", # Python 3.13 support
-  "opencv-python-headless >=4.10", # NumPy 2 support
+  "numpy >=2.3", # Windows ARM64 wheels
   "packaging >=20.0", # py.typed
   # When needed, dev builds can be found at https://download.qt.io/snapshots/ci/pyside/dev?C=M;O=D
-  "PySide6-Essentials <6.8.1", # Has typing issue with QMessageBox.warning https://bugreports.qt.io/browse/PYSIDE-2939
-  # "PySide6-Essentials >=6.8.2", # Fixed typing issue with QMessageBox.warning
-  "scipy >=1.14.1", # Python 3.13 support
+  "PySide6-Essentials", # Let package resolution find the minimum for wheels (>=6.9.0 on Windows ARM64; <6.8.1 on ubuntu-22.04-arm (glibc 2.39))
   "tomli-w >=1.1.0", # Typing fixes
 
+  # scipy is used for pHash calculation as a smaller, but still fast implementation.
+  # However, scipy is not available on all environments yet.
+  # In those cases, we're falling back to opencv-contrib-python's cv2.img_hash
+  "opencv-contrib-python-headless >=4.10; platform_machine == 'aarch64'", # NumPy 2 support
+  "opencv-python-headless >=4.10; platform_machine != 'aarch64'", # NumPy 2 support
+  "scipy >=1.14.1; platform_machine != 'aarch64'", # Python 3.13 support
+
   #
   # Build and compile resources
   "pyinstaller >=6.14.0", # Mitigate issues with pkg_resources deprecation warning
@@ -55,6 +59,7 @@ dev = [
   "ruff >=0.11.13",
   #
   # Types
+  "opencv-contrib-python-headless",
   "scipy-stubs >=1.14.1.1",
   "types-PyAutoGUI",
   "types-PyScreeze; sys_platform == 'linux'",
diff --git a/src/compare.py b/src/compare.py
@@ -5,7 +5,6 @@
 import Levenshtein
 import numpy as np
 from cv2.typing import MatLike
-from scipy import fft
 
 from utils import (
     BGRA_CHANNEL_COUNT,
@@ -90,27 +89,40 @@ def compare_template(source: MatLike, capture: MatLike, mask: MatLike | None = N
     return 1 - (min_val / max_error)
 
 
-def __cv2_phash(image: MatLike, hash_size: int = 8, highfreq_factor: int = 4):
-    """Implementation copied from https://github.com/JohannesBuchner/imagehash/blob/38005924fe9be17cfed145bbc6d83b09ef8be025/imagehash/__init__.py#L260 ."""  # noqa: E501
-    # OpenCV has its own pHash comparison implementation in `cv2.img_hash`,
-    # but it requires contrib/extra modules and is inaccurate
-    # unless we precompute the size with a specific interpolation.
-    # See: https://github.com/opencv/opencv_contrib/issues/3295#issuecomment-1172878684
-    #
-    # pHash = cv2.img_hash.PHash.create()
-    # source = cv2.resize(source, (8, 8), interpolation=cv2.INTER_AREA)
-    # capture = cv2.resize(capture, (8, 8), interpolation=cv2.INTER_AREA)
-    # source_hash = pHash.compute(source)
-    # capture_hash = pHash.compute(capture)
-    # hash_diff = pHash.compare(source_hash, capture_hash)
-
-    img_size = hash_size * highfreq_factor
-    image = cv2.cvtColor(image, cv2.COLOR_BGRA2GRAY)
-    image = cv2.resize(image, (img_size, img_size), interpolation=cv2.INTER_AREA)
-    dct = fft.dct(fft.dct(image, axis=0), axis=1)
-    dct_low_frequency = dct[:hash_size, :hash_size]
-    median = np.median(dct_low_frequency)
-    return dct_low_frequency > median
+try:
+    from scipy import fft
+
+    def __cv2_scipy_compute_phash(image: MatLike, hash_size: int, highfreq_factor: int = 4):
+        """Implementation copied from https://github.com/JohannesBuchner/imagehash/blob/38005924fe9be17cfed145bbc6d83b09ef8be025/imagehash/__init__.py#L260 ."""  # noqa: E501
+        img_size = hash_size * highfreq_factor
+        image = cv2.cvtColor(image, cv2.COLOR_BGRA2GRAY)
+        image = cv2.resize(image, (img_size, img_size), interpolation=cv2.INTER_AREA)
+        dct = fft.dct(fft.dct(image, axis=0), axis=1)
+        dct_low_frequency = dct[:hash_size, :hash_size]
+        median = np.median(dct_low_frequency)
+        return dct_low_frequency > median
+
+    def __cv2_phash(source: MatLike, capture: MatLike, hash_size: int = 8):  # pyright: ignore[reportRedeclaration]
+        source_hash = __cv2_scipy_compute_phash(source, hash_size)
+        capture_hash = __cv2_scipy_compute_phash(capture, hash_size)
+        hash_diff = np.count_nonzero(source_hash != capture_hash)
+        return 1 - (hash_diff / 64.0)
+
+except ModuleNotFoundError:
+
+    def __cv2_phash(source: MatLike, capture: MatLike, hash_size: int = 8):
+        # OpenCV has its own pHash comparison implementation in `cv2.img_hash`,
+        # but it requires contrib/extra modules and is inaccurate
+        # unless we precompute the size with a specific interpolation.
+        # See: https://github.com/opencv/opencv_contrib/issues/3295#issuecomment-1172878684
+        #
+        phash = cv2.img_hash.PHash.create()
+        source = cv2.resize(source, (hash_size, hash_size), interpolation=cv2.INTER_AREA)
+        capture = cv2.resize(capture, (hash_size, hash_size), interpolation=cv2.INTER_AREA)
+        source_hash = phash.compute(source)
+        capture_hash = phash.compute(capture)
+        hash_diff = phash.compare(source_hash, capture_hash)
+        return 1 - (hash_diff / 64.0)
 
 
 def compare_phash(source: MatLike, capture: MatLike, mask: MatLike | None = None):
@@ -130,11 +142,7 @@ def compare_phash(source: MatLike, capture: MatLike, mask: MatLike | None = None
         source = cv2.bitwise_and(source, source, mask=mask)
         capture = cv2.bitwise_and(capture, capture, mask=mask)
 
-    source_hash = __cv2_phash(source)
-    capture_hash = __cv2_phash(capture)
-    hash_diff = np.count_nonzero(source_hash != capture_hash)
-
-    return 1 - (hash_diff / 64.0)
+    return __cv2_phash(source, capture)
 
 
 def extract_and_compare_text(capture: MatLike, texts: Iterable[str], methods_index: Iterable[int]):
diff --git a/uv.lock b/uv.lock
