ScreenMagnifier 1.11.0.post8__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (137) hide show
  1. screenmagnifier-1.11.0.post8/MANIFEST.in +8 -0
  2. screenmagnifier-1.11.0.post8/PKG-INFO +591 -0
  3. screenmagnifier-1.11.0.post8/README.md +542 -0
  4. screenmagnifier-1.11.0.post8/ScreenMagnifier/__init__.py +68 -0
  5. screenmagnifier-1.11.0.post8/ScreenMagnifier/__main__.py +17 -0
  6. screenmagnifier-1.11.0.post8/ScreenMagnifier/advancedoverlay.py +593 -0
  7. screenmagnifier-1.11.0.post8/ScreenMagnifier/advancedpanel.py +521 -0
  8. screenmagnifier-1.11.0.post8/ScreenMagnifier/analysiscontroller.py +533 -0
  9. screenmagnifier-1.11.0.post8/ScreenMagnifier/analysisserver.py +404 -0
  10. screenmagnifier-1.11.0.post8/ScreenMagnifier/colordetector/__init__.py +28 -0
  11. screenmagnifier-1.11.0.post8/ScreenMagnifier/colordetector/colordetector.py +570 -0
  12. screenmagnifier-1.11.0.post8/ScreenMagnifier/colordetector/core.py +434 -0
  13. screenmagnifier-1.11.0.post8/ScreenMagnifier/colordetector/main.py +23 -0
  14. screenmagnifier-1.11.0.post8/ScreenMagnifier/colordetector/mainwindow.py +182 -0
  15. screenmagnifier-1.11.0.post8/ScreenMagnifier/colorpanel.py +424 -0
  16. screenmagnifier-1.11.0.post8/ScreenMagnifier/colorswatches/__init__.py +16 -0
  17. screenmagnifier-1.11.0.post8/ScreenMagnifier/colorswatches/colorswatches.py +316 -0
  18. screenmagnifier-1.11.0.post8/ScreenMagnifier/colorswatches/main.py +23 -0
  19. screenmagnifier-1.11.0.post8/ScreenMagnifier/colorswatches/mainwindow.py +60 -0
  20. screenmagnifier-1.11.0.post8/ScreenMagnifier/controlpanel.py +234 -0
  21. screenmagnifier-1.11.0.post8/ScreenMagnifier/detectionpanel.py +790 -0
  22. screenmagnifier-1.11.0.post8/ScreenMagnifier/facedetector/__init__.py +24 -0
  23. screenmagnifier-1.11.0.post8/ScreenMagnifier/facedetector/core.py +314 -0
  24. screenmagnifier-1.11.0.post8/ScreenMagnifier/facedetector/facedetector.py +288 -0
  25. screenmagnifier-1.11.0.post8/ScreenMagnifier/facedetector/main.py +23 -0
  26. screenmagnifier-1.11.0.post8/ScreenMagnifier/facedetector/mainwindow.py +122 -0
  27. screenmagnifier-1.11.0.post8/ScreenMagnifier/facedetector/models/__init__.py +4 -0
  28. screenmagnifier-1.11.0.post8/ScreenMagnifier/facepointer.py +1121 -0
  29. screenmagnifier-1.11.0.post8/ScreenMagnifier/features.py +50 -0
  30. screenmagnifier-1.11.0.post8/ScreenMagnifier/hotkeys/__init__.py +16 -0
  31. screenmagnifier-1.11.0.post8/ScreenMagnifier/hotkeys/hotkeys.py +379 -0
  32. screenmagnifier-1.11.0.post8/ScreenMagnifier/hotkeys/main.py +23 -0
  33. screenmagnifier-1.11.0.post8/ScreenMagnifier/hotkeys/mainwindow.py +56 -0
  34. screenmagnifier-1.11.0.post8/ScreenMagnifier/imagefilters/__init__.py +24 -0
  35. screenmagnifier-1.11.0.post8/ScreenMagnifier/imagefilters/core.py +172 -0
  36. screenmagnifier-1.11.0.post8/ScreenMagnifier/imagefilters/imagefilters.py +220 -0
  37. screenmagnifier-1.11.0.post8/ScreenMagnifier/imagefilters/main.py +23 -0
  38. screenmagnifier-1.11.0.post8/ScreenMagnifier/imagefilters/mainwindow.py +120 -0
  39. screenmagnifier-1.11.0.post8/ScreenMagnifier/magnifierview/__init__.py +16 -0
  40. screenmagnifier-1.11.0.post8/ScreenMagnifier/magnifierview/magnifierview.py +1249 -0
  41. screenmagnifier-1.11.0.post8/ScreenMagnifier/magnifierview/main.py +23 -0
  42. screenmagnifier-1.11.0.post8/ScreenMagnifier/magnifierview/mainwindow.py +91 -0
  43. screenmagnifier-1.11.0.post8/ScreenMagnifier/main.py +157 -0
  44. screenmagnifier-1.11.0.post8/ScreenMagnifier/mainwindow.py +1368 -0
  45. screenmagnifier-1.11.0.post8/ScreenMagnifier/mousecatcher/__init__.py +16 -0
  46. screenmagnifier-1.11.0.post8/ScreenMagnifier/mousecatcher/main.py +23 -0
  47. screenmagnifier-1.11.0.post8/ScreenMagnifier/mousecatcher/mainwindow.py +78 -0
  48. screenmagnifier-1.11.0.post8/ScreenMagnifier/mousecatcher/mousecatcher.py +251 -0
  49. screenmagnifier-1.11.0.post8/ScreenMagnifier/mousemove.py +259 -0
  50. screenmagnifier-1.11.0.post8/ScreenMagnifier/netprotocol/__init__.py +25 -0
  51. screenmagnifier-1.11.0.post8/ScreenMagnifier/netprotocol/main.py +23 -0
  52. screenmagnifier-1.11.0.post8/ScreenMagnifier/netprotocol/mainwindow.py +91 -0
  53. screenmagnifier-1.11.0.post8/ScreenMagnifier/netprotocol/netprotocol.py +372 -0
  54. screenmagnifier-1.11.0.post8/ScreenMagnifier/netprotocol/wire.py +189 -0
  55. screenmagnifier-1.11.0.post8/ScreenMagnifier/regionselector/__init__.py +16 -0
  56. screenmagnifier-1.11.0.post8/ScreenMagnifier/regionselector/main.py +23 -0
  57. screenmagnifier-1.11.0.post8/ScreenMagnifier/regionselector/mainwindow.py +70 -0
  58. screenmagnifier-1.11.0.post8/ScreenMagnifier/regionselector/regionselector.py +549 -0
  59. screenmagnifier-1.11.0.post8/ScreenMagnifier/remoteclient.py +636 -0
  60. screenmagnifier-1.11.0.post8/ScreenMagnifier/resources/icon-128.png +0 -0
  61. screenmagnifier-1.11.0.post8/ScreenMagnifier/resources/icon-16.png +0 -0
  62. screenmagnifier-1.11.0.post8/ScreenMagnifier/resources/icon-24.png +0 -0
  63. screenmagnifier-1.11.0.post8/ScreenMagnifier/resources/icon-256.png +0 -0
  64. screenmagnifier-1.11.0.post8/ScreenMagnifier/resources/icon-32.png +0 -0
  65. screenmagnifier-1.11.0.post8/ScreenMagnifier/resources/icon-48.png +0 -0
  66. screenmagnifier-1.11.0.post8/ScreenMagnifier/resources/icon-512.png +0 -0
  67. screenmagnifier-1.11.0.post8/ScreenMagnifier/resources/icon-64.png +0 -0
  68. screenmagnifier-1.11.0.post8/ScreenMagnifier/resources/icon.icns +0 -0
  69. screenmagnifier-1.11.0.post8/ScreenMagnifier/resources/icon.ico +0 -0
  70. screenmagnifier-1.11.0.post8/ScreenMagnifier/screengrabber/__init__.py +16 -0
  71. screenmagnifier-1.11.0.post8/ScreenMagnifier/screengrabber/main.py +23 -0
  72. screenmagnifier-1.11.0.post8/ScreenMagnifier/screengrabber/mainwindow.py +79 -0
  73. screenmagnifier-1.11.0.post8/ScreenMagnifier/screengrabber/screengrabber.py +558 -0
  74. screenmagnifier-1.11.0.post8/ScreenMagnifier/server.py +150 -0
  75. screenmagnifier-1.11.0.post8/ScreenMagnifier/serverpanel.py +379 -0
  76. screenmagnifier-1.11.0.post8/ScreenMagnifier/shortcuteditor/__init__.py +16 -0
  77. screenmagnifier-1.11.0.post8/ScreenMagnifier/shortcuteditor/main.py +23 -0
  78. screenmagnifier-1.11.0.post8/ScreenMagnifier/shortcuteditor/mainwindow.py +54 -0
  79. screenmagnifier-1.11.0.post8/ScreenMagnifier/shortcuteditor/shortcuteditor.py +411 -0
  80. screenmagnifier-1.11.0.post8/ScreenMagnifier/shortcuts.py +118 -0
  81. screenmagnifier-1.11.0.post8/ScreenMagnifier/shortcutspanel.py +140 -0
  82. screenmagnifier-1.11.0.post8/ScreenMagnifier/support.py +127 -0
  83. screenmagnifier-1.11.0.post8/ScreenMagnifier/translations/ar.json +387 -0
  84. screenmagnifier-1.11.0.post8/ScreenMagnifier/translations/de.json +387 -0
  85. screenmagnifier-1.11.0.post8/ScreenMagnifier/translations/es.json +387 -0
  86. screenmagnifier-1.11.0.post8/ScreenMagnifier/translations/fr.json +387 -0
  87. screenmagnifier-1.11.0.post8/ScreenMagnifier/translations/it.json +387 -0
  88. screenmagnifier-1.11.0.post8/ScreenMagnifier/translations/ja.json +387 -0
  89. screenmagnifier-1.11.0.post8/ScreenMagnifier/translations/ko.json +387 -0
  90. screenmagnifier-1.11.0.post8/ScreenMagnifier/translations/pt_BR.json +387 -0
  91. screenmagnifier-1.11.0.post8/ScreenMagnifier/translations/ru.json +387 -0
  92. screenmagnifier-1.11.0.post8/ScreenMagnifier/translations/tr.json +387 -0
  93. screenmagnifier-1.11.0.post8/ScreenMagnifier/translations/zh_CN.json +387 -0
  94. screenmagnifier-1.11.0.post8/ScreenMagnifier/translator/__init__.py +16 -0
  95. screenmagnifier-1.11.0.post8/ScreenMagnifier/translator/main.py +23 -0
  96. screenmagnifier-1.11.0.post8/ScreenMagnifier/translator/mainwindow.py +62 -0
  97. screenmagnifier-1.11.0.post8/ScreenMagnifier/translator/translator.py +284 -0
  98. screenmagnifier-1.11.0.post8/ScreenMagnifier/upscaler/__init__.py +24 -0
  99. screenmagnifier-1.11.0.post8/ScreenMagnifier/upscaler/core.py +315 -0
  100. screenmagnifier-1.11.0.post8/ScreenMagnifier/upscaler/main.py +23 -0
  101. screenmagnifier-1.11.0.post8/ScreenMagnifier/upscaler/mainwindow.py +128 -0
  102. screenmagnifier-1.11.0.post8/ScreenMagnifier/upscaler/models/FSRCNN-small_x2.pb +0 -0
  103. screenmagnifier-1.11.0.post8/ScreenMagnifier/upscaler/models/FSRCNN-small_x3.pb +0 -0
  104. screenmagnifier-1.11.0.post8/ScreenMagnifier/upscaler/models/FSRCNN-small_x4.pb +0 -0
  105. screenmagnifier-1.11.0.post8/ScreenMagnifier/upscaler/models/FSRCNN_x2.pb +0 -0
  106. screenmagnifier-1.11.0.post8/ScreenMagnifier/upscaler/models/FSRCNN_x3.pb +0 -0
  107. screenmagnifier-1.11.0.post8/ScreenMagnifier/upscaler/models/FSRCNN_x4.pb +0 -0
  108. screenmagnifier-1.11.0.post8/ScreenMagnifier/upscaler/models/LICENSE-FSRCNN +201 -0
  109. screenmagnifier-1.11.0.post8/ScreenMagnifier/upscaler/models/__init__.py +4 -0
  110. screenmagnifier-1.11.0.post8/ScreenMagnifier/upscaler/upscaler.py +285 -0
  111. screenmagnifier-1.11.0.post8/ScreenMagnifier/wincheck.py +65 -0
  112. screenmagnifier-1.11.0.post8/ScreenMagnifier/zoomoverlay/__init__.py +16 -0
  113. screenmagnifier-1.11.0.post8/ScreenMagnifier/zoomoverlay/main.py +23 -0
  114. screenmagnifier-1.11.0.post8/ScreenMagnifier/zoomoverlay/mainwindow.py +99 -0
  115. screenmagnifier-1.11.0.post8/ScreenMagnifier/zoomoverlay/zoomoverlay.py +1779 -0
  116. screenmagnifier-1.11.0.post8/ScreenMagnifier.egg-info/PKG-INFO +591 -0
  117. screenmagnifier-1.11.0.post8/ScreenMagnifier.egg-info/SOURCES.txt +135 -0
  118. screenmagnifier-1.11.0.post8/ScreenMagnifier.egg-info/dependency_links.txt +1 -0
  119. screenmagnifier-1.11.0.post8/ScreenMagnifier.egg-info/entry_points.txt +5 -0
  120. screenmagnifier-1.11.0.post8/ScreenMagnifier.egg-info/requires.txt +19 -0
  121. screenmagnifier-1.11.0.post8/ScreenMagnifier.egg-info/top_level.txt +1 -0
  122. screenmagnifier-1.11.0.post8/docs/banner.png +0 -0
  123. screenmagnifier-1.11.0.post8/docs/icon-small.svg +59 -0
  124. screenmagnifier-1.11.0.post8/docs/icon.svg +89 -0
  125. screenmagnifier-1.11.0.post8/docs/make_banner.py +108 -0
  126. screenmagnifier-1.11.0.post8/docs/make_icons.py +44 -0
  127. screenmagnifier-1.11.0.post8/docs/make_screenshot.py +131 -0
  128. screenmagnifier-1.11.0.post8/docs/screenshot.png +0 -0
  129. screenmagnifier-1.11.0.post8/pyproject.toml +3 -0
  130. screenmagnifier-1.11.0.post8/requirements.txt +4 -0
  131. screenmagnifier-1.11.0.post8/setup.cfg +4 -0
  132. screenmagnifier-1.11.0.post8/setup.py +67 -0
  133. screenmagnifier-1.11.0.post8/tests/test_facepointer.py +159 -0
  134. screenmagnifier-1.11.0.post8/tests/test_filters.py +47 -0
  135. screenmagnifier-1.11.0.post8/tests/test_package.py +114 -0
  136. screenmagnifier-1.11.0.post8/tests/test_server.py +56 -0
  137. screenmagnifier-1.11.0.post8/tests/test_translations.py +73 -0
@@ -0,0 +1,8 @@
1
+ include README.md requirements.txt setup.py pyproject.toml
2
+ recursive-include ScreenMagnifier/upscaler/models *.pb LICENSE*
3
+ recursive-include ScreenMagnifier/resources *.png *.ico *.icns
4
+ recursive-include ScreenMagnifier/translations *.json
5
+ recursive-include docs *.svg *.png *.py
6
+ recursive-include tests *.py
7
+ prune .github
8
+ global-exclude *.py[cod] __pycache__ _buildinfo.py
@@ -0,0 +1,591 @@
1
+ Metadata-Version: 2.4
2
+ Name: ScreenMagnifier
3
+ Version: 1.11.0.post8
4
+ Summary: Real-time screen magnifier with AI upscaling, an in-game zoomer, a screen color picker, color / face detection and an optional analysis server - PyQt5 / PyQt6 / PySide through ManyQt.
5
+ Author: UsamaTN
6
+ Author-email: ininou.oussematn@gmail.com
7
+ Project-URL: Donate (Ko-fi), https://ko-fi.com/usamatn
8
+ Project-URL: Donate (ba9chich), https://ba9chich.com/fr/IninouUsama
9
+ Keywords: magnifier,zoom,screen,color picker,eyedropper,super-resolution,accessibility,PyQt5,PyQt6,PySide6
10
+ Classifier: Development Status :: 4 - Beta
11
+ Classifier: Environment :: X11 Applications :: Qt
12
+ Classifier: Environment :: Win32 (MS Windows)
13
+ Classifier: Environment :: MacOS X
14
+ Classifier: Intended Audience :: End Users/Desktop
15
+ Classifier: Intended Audience :: Developers
16
+ Classifier: Operating System :: Microsoft :: Windows
17
+ Classifier: Operating System :: MacOS
18
+ Classifier: Operating System :: POSIX :: Linux
19
+ Classifier: Programming Language :: Python :: 3
20
+ Classifier: Topic :: Desktop Environment
21
+ Classifier: Topic :: Multimedia :: Graphics :: Viewers
22
+ Requires-Python: >=3.8
23
+ Description-Content-Type: text/markdown
24
+ Requires-Dist: ManyQt>=0.5
25
+ Requires-Dist: numpy>=1.19
26
+ Requires-Dist: pynput>=1.7
27
+ Provides-Extra: pyqt6
28
+ Requires-Dist: PyQt6; extra == "pyqt6"
29
+ Provides-Extra: pyqt5
30
+ Requires-Dist: PyQt5; extra == "pyqt5"
31
+ Provides-Extra: pyside6
32
+ Requires-Dist: PySide6; extra == "pyside6"
33
+ Provides-Extra: opencv
34
+ Requires-Dist: opencv-contrib-python-headless<5,>=4.8; extra == "opencv"
35
+ Provides-Extra: all
36
+ Requires-Dist: PyQt6; extra == "all"
37
+ Requires-Dist: opencv-contrib-python-headless<5,>=4.8; extra == "all"
38
+ Dynamic: author
39
+ Dynamic: author-email
40
+ Dynamic: classifier
41
+ Dynamic: description
42
+ Dynamic: description-content-type
43
+ Dynamic: keywords
44
+ Dynamic: project-url
45
+ Dynamic: provides-extra
46
+ Dynamic: requires-dist
47
+ Dynamic: requires-python
48
+ Dynamic: summary
49
+
50
+ # ScreenMagnifier
51
+
52
+ <p align="center"><img src="docs/banner.png" alt="ScreenMagnifier - real-time screen magnifier for Windows, macOS and Linux" width="100%"></p>
53
+
54
+ A real-time screen magnifier written in Python with **PyQt/PySide** through
55
+ [ManyQt](https://github.com/Usama01TN/ManyQt): select any screen region (or follow the mouse
56
+ cursor), zoom from 0.25× to 32×, and upscale the live image with classic or AI super-resolution
57
+ filters. Color detection, optional AI face detection and an optional analysis server (upscaling and analysis
58
+ on another computer, in real time) are built in.
59
+
60
+ ![ScreenMagnifier: the magnifier with a color zone (left of the panel), the zoomer pinned on the roof with its live color code (top left) and the Colors tab showing the same live color](docs/screenshot.png)
61
+
62
+ *The magnifier (Pixel art upscaler, 2.4x) outlines the red roof as a color zone; the zoomer, pinned on it, shows its
63
+ live color code and zone; the Colors tab follows the same live color. Captured from the running application.*
64
+
65
+ ## Goal:
66
+
67
+ Inspect small UI details, read tiny text, check pixel alignment and pick colours, with an image that
68
+ stays sharp at high magnification instead of turning into a blurry or blocky mess.
69
+
70
+ ## In-advanced zoom (works while you play):
71
+
72
+ Start the app (optionally straight into the tray with `python main.py --tray`), switch to your game and press:
73
+
74
+ | Global hotkey | Action |
75
+ |-------------------------|--------------------------------------------------------------------------|
76
+ | **Ctrl+Alt+Z** | Show / hide the zoom lens |
77
+ | Ctrl+Alt+= / Ctrl+Alt+- | Zoom in / out (1x - 16x) |
78
+ | Ctrl+Alt+X | Pin the target at the current mouse position |
79
+ | Ctrl+Alt+C | Cycle the target: screen centre -> pinned point -> mouse cursor |
80
+ | Ctrl+Alt+K | Copy the zoomer color code (when *Color code under the crosshair* is on) |
81
+ | Ctrl+Alt+P | Screen color picker: live zoom at the mouse, click anywhere to copy |
82
+
83
+ All hotkeys - and every window shortcut - are rebindable in the **Shortcuts** tab (click a field, press the new
84
+ combination) and every
85
+ setting is saved between launches.
86
+
87
+ - The lens is **click-through and never takes focus**: the game keeps receiving every key and mouse click,
88
+ even clicks made directly on the lens.
89
+ - **Target**: screen centre (your crosshair), a pinned point (e.g. the minimap), or the mouse cursor.
90
+ - **Placement**: *On target* (scope style, the lens sits over what it magnifies), any screen corner
91
+ (picture-in-picture), next to the target, a **custom area** or **full screen**. Circle, rounded square (with an
92
+ adjustable **corner radius**, 0-200 px: square corners to pill / circle) or rectangle, size 160-900 px,
93
+ opacity, crosshair, 15-144 fps.
94
+ - **Filters** (Zoomer tab): Grayscale, Sepia, Invert, High contrast, Warm (less blue light), Night vision,
95
+ Thermal (false colors), Outline (edges) and **color-blindness help** (red-, green- or blue-weak), with a
96
+ Strength slider, plus Brightness / Contrast / Saturation. The copied color code stays the true screen color.
97
+ The color-blindness filters keep whites and greys unchanged; on random colors they cut the pairs a red-,
98
+ green- or blue-weak viewer confuses by 20 %, 38 % and 67 % (measured with a standard simulation, not with
99
+ viewers - the picture looks unusual to typical vision; Strength softens it).
100
+ - **Custom area**: *Draw the area on the screen...* and drag a rectangle anywhere (any size and aspect ratio),
101
+ or type its position and size. The magnified area follows the shape of the lens.
102
+ - **Full screen**: the lens covers a whole screen (the screen of the target, or one you choose) - a full-screen
103
+ zoom for games and videos. Press the zoomer shortcut (Ctrl+Alt+Z) to hide it. A lens that covers what it
104
+ magnifies must be hidden from screen capture: Windows 10 (2004+) / 11 does it; elsewhere a full-screen lens
105
+ moves to **your other screen** automatically (two monitors: screen 1 magnified on screen 2), or to a corner
106
+ with one screen.
107
+ - Closing the window keeps the app running in the **system tray**; right-click the tray icon -> Quit to exit.
108
+ The main magnifier stops capturing while hidden, so only the lens costs CPU while you play.
109
+ - The lens uses the upscaler selected in the Settings tab (AI super-resolution by default when available).
110
+
111
+ Requirements and limits:
112
+
113
+ - Run the game in **borderless / windowed full-screen**. Exclusive full-screen bypasses the desktop
114
+ compositor and no overlay can be drawn over it.
115
+ - *On target* (scope) placement must never capture the lens itself. The app tries, in order:
116
+ 1. **Hide the lens from capture** (Windows 10 2004+ / 11), verified with a tiny 16 px probe pattern.
117
+ The lens is a constant-alpha window: Windows refuses (error 8) to hide per-pixel-alpha windows.
118
+ 2. **Capture the game window directly** (PrintWindow, like OBS "Window Capture"): the lens floats above
119
+ the game window, so it can never appear in that capture, whatever Windows says about hiding.
120
+ 3. Otherwise the lens moves to a free corner. The *Zoomer* tab always shows which mode is active
121
+ and why. On Linux / macOS the corner is used.
122
+ - Troubleshooting on Windows: run `python wincheck.py` and send its 4-line report.
123
+ - On Windows the hotkey combination is consumed (the game does not see it). With pynput (Linux / macOS)
124
+ the game also receives it, so pick combinations your game does not use. On Wayland, global hotkeys
125
+ and screen capture need XWayland (`QT_QPA_PLATFORM=xcb`); on macOS grant Accessibility and Screen
126
+ Recording permissions.
127
+ - Some competitive games forbid screen-zoom tools in their rules or anti-cheat; check before using it online.
128
+
129
+ ## Color codes (color picker):
130
+
131
+ **One live color, one text everywhere.** Whatever you point at is *the* live color - the magnifier while the mouse
132
+ is over it, otherwise the zoomer crosshair (when its color code is on), the screen color picker while it runs. The
133
+ *Colors* tab (**LIVE COLOR**, with where it comes from), the zoomer color code and the eyedropper bubble show it
134
+ with the same code - in the *default copy format* (e.g. `rgb(225, 16, 32)`), so **the code shown is always the code
135
+ copied** - the same color name and the same color zone. *Pick from* tells whether codes come from the zoomed image
136
+ or the exact screen pixel (the screen color picker is always pixel-exact).
137
+
138
+ Copy the color code of any pixel to the clipboard - from the real screen, live, without the window:
139
+
140
+ - **Screen color picker - Ctrl+Alt+P anywhere** (any application or game; also *Pick from screen* in the toolbar,
141
+ Ctrl+Shift+P): a pixel-exact zoom lens with a pixel grid follows the mouse beside the cursor and shows the **live**
142
+ color of the pixel under the crosshair (swatch, HEX, RGB) on every frame. **Left click anywhere** copies
143
+ it (the click does not reach the application underneath), **Ctrl+Alt+P** again copies too, **right-click / Esc**
144
+ cancels, the **wheel** zooms, the **arrow keys** move the cursor by 1 px (Linux). The exact screen pixel at the
145
+ click is copied, in the default format, and added to the history. Click capture: X11 pointer grab on Linux, a
146
+ low-level mouse hook on Windows, an event tap on macOS (needs the *Accessibility* permission, like the hotkeys).
147
+ - **Zoomer color code (optional)**: *Zoomer* tab -> *Color tools in the zoomer* -> *Color code under the crosshair*
148
+ (off by default) shows the live HEX / RGB of the crosshair pixel - and the name of the color zone it is in, when
149
+ *Color zones* is on too. **Ctrl+Alt+K** copies exactly the code shown (same pick source and sample size as the
150
+ *Colors* tab); with the color code off, the hotkey copies nothing and says why.
151
+ - **Pick color** (toolbar, **I**): eyedropper on the zoomed screen - a bubble shows the color under the cursor,
152
+ every click copies it (no panning while picking), **Esc** stops. Colors are read from the **zoomed image as you
153
+ see it** (after upscaling, sharpening, inversion); *Pick from: Original screen pixel* in the *Colors* tab reads
154
+ the untouched screen pixel instead. Every way of copying below follows that choice.
155
+ - **C**: copies the color under the mouse in the magnifier, in the default format.
156
+ - **Right-click** in the magnifier: menu with the color in every format (default format first).
157
+ - **Left click** (optional, *Colors* tab): copy on click. Detection's *Pick* mode takes precedence.
158
+ - **Ctrl+Alt+P anywhere**: the screen color picker above (rebindable in the *Shortcuts* tab).
159
+ - **13 formats**: `#3A7BD5`, `#3a7bd5`, `3A7BD5`, `rgb(58, 123, 213)`, `58, 123, 213`,
160
+ `0.227, 0.482, 0.835`, `hsl(215, 65%, 53%)`, `hsv(215, 73%, 84%)`, `cmyk(73%, 42%, 0%, 16%)`,
161
+ `lab(51.7% 9.7 -52.3)`, `QColor(58, 123, 213)`, `0x3A7BD5`, `cornflowerblue` - or *Copy all formats*.
162
+ - **Sample**: 1 pixel, or the average of 3 x 3, 5 x 5 or 9 x 9 pixels (steadier on anti-aliased text and
163
+ textures).
164
+ - **Confirmation**: an animated "#3A7BD5 copied" bubble with a swatch, in the magnifier or in the lens.
165
+ - **History**: the last 32 copied colors as swatches (click: copy again, right-click: remove), kept between
166
+ sessions; *Copy history* copies them all.
167
+ - The *Colors* tab also shows the color under the mouse in every format, each with its own *Copy* button, and
168
+ the WCAG contrast checker.
169
+
170
+ ## Color detection:
171
+
172
+ *Detection* tab -> **Detect target colors**.
173
+
174
+ - **Target colors**: *Add...* (color dialog) or *Pick* + a click in the magnifier. The click is refined: on
175
+ thin text or icon edges (anti-aliased, pale pixels) and in noisy images, the object's typical color is used,
176
+ so clicking anywhere on a red word gives the same result.
177
+ - **Match: Similar shades** (default): same hue at any lightness - shading, shadows, highlights and
178
+ anti-aliased text of the target color all match; tolerance = hue in degrees (15 by default). Grey, white and
179
+ black targets match similar neutral pixels. Muted look-alikes (e.g. brown for red) need strong evidence (hysteresis),
180
+ so they do not produce false boxes.
181
+ - **Match: Exact color**: only colors within a delta E distance (CIE Lab), e.g. to check one precise UI color.
182
+ Use it too when "every shade" is too broad (a red-tinted photo contains many shades of red).
183
+ - **Group nearby** (5 px): the letters and words of a text line, or a noisy object, form one box; thin strokes (1 px
184
+ text, lines) are kept; isolated noise pixels are ignored.
185
+ - **Moving content**: boxes and the mask stay locked onto the screen content in follow-cursor mode and in the
186
+ Zoomer lens (each result carries the screen position of its frame).
187
+ - **Highlight mask**: *Isolate* dims everything that does not match, *Tint* paints the matches with a vivid
188
+ complementary color.
189
+ - **Dominant colors**: a stable palette bar (no flicker between frames) with names and shares.
190
+ - **Color codes and contrast**: see *Color codes* above (*Colors* tab).
191
+ - **Alerts**: a status bar (or tray, while you play) message when a target color appears.
192
+ - **Where**: *Show the zones in: the magnifier / the zoomer* (Detection tab) - independent switches; the zoomer one
193
+ is the same setting as *Color zones* in the Zoomer tab.
194
+
195
+ Measured on test scenes with exact ground truth (anti-aliased red text, 1 px line, button, icon, a shaded red
196
+ sphere, a red cube in shadow, a noisy health bar, and pink / orange / magenta / brown look-alikes): 100 % of the
197
+ red objects found, one box per object, no false matches; 173 different click positions on the objects: no
198
+ false boxes. About 15-30 ms per 800x500 frame on a worker thread; unchanged frames are not analysed again.
199
+ With the analysis server, frames travel losslessly (exact colors).
200
+
201
+ ## Face detection (optional AI):
202
+
203
+ *Detection* tab -> **Detect faces** (off by default).
204
+
205
+ - **YuNet** (OpenCV DNN, MIT license): accurate, confidence score and 5 landmarks. The 232 KB model is
206
+ downloaded once with *Download model* from the official OpenCV model zoo and verified with SHA-256 before
207
+ use (`python server.py --download-face-model` does the same for a server).
208
+ - **Haar cascade**: ships with opencv-python, works immediately, frontal faces only. Local contrast
209
+ equalisation (CLAHE): letterbox bars or a plain desktop around a video do not hide the faces.
210
+ - **Modes**: boxes, boxes + landmarks, or **privacy blur** (pixelates every face in the magnifier and lens).
211
+
212
+ ### Face pointer (watching films)
213
+
214
+ *Detection* tab -> **Follow the faces on the screen**, or **Ctrl+Alt+F** anywhere: the mouse pointer glides to
215
+ the faces of the film (the largest one, or the one nearest the pointer), and stays with a face while it moves.
216
+
217
+ - **What follows the face**: the mouse pointer, or **only the zoomer** - the zoomer magnifies the face and the
218
+ pointer stays still (video players show their controls when the pointer moves).
219
+ - Move the mouse yourself to take the control back: it pauses (1-10 s, your choice), then follows again.
220
+ - The whole screen of the pointer is scanned a few times per second in the background (faces from ~48 px on a
221
+ 1080p screen with Haar; the YuNet model finds smaller faces, faster). This application's windows and the
222
+ zoomer lens are ignored, so a magnified face is never chased.
223
+ - Wayland, and macOS without the Accessibility permission, do not let applications move the pointer: the
224
+ face pointer says so - choose *Only the zoomer* there.
225
+
226
+ **Offline games** (*How to move*):
227
+
228
+ - **Automatic** (default): moves the pointer (films, menus) and **centres the enemy's face on the screen** while a
229
+ game captures the mouse - the system says the pointer is confined (Windows) or hidden while it is moved (a
230
+ resting video player shows it again), or the game puts it back on the same spot. When a menu shows the pointer
231
+ again, the pointer is moved again.
232
+ - Games that show a pointer (strategy, adventure, top-down): *Move the pointer to the face*.
233
+ - Games that capture the mouse (first-person, 3D): *Turn the view to the face* sends mouse movements, like a real
234
+ mouse, until the face is at the crosshair (the screen centre), in real time (~30 times per second): the area
235
+ around the crosshair is captured at full resolution; once a face is followed, it is tracked around its expected
236
+ position.
237
+ - The game's mouse sensitivity is **measured from the picture** (how far the scene turns for the movements sent,
238
+ over ~0.5 s; inverted axes included): no calibration, from very low to very high sensitivities.
239
+ - *When*: **While the right mouse button is held** (aim) assists only then, so your own aiming is never fought.
240
+ - **Assist area** around the crosshair: faces farther away are ignored. A face that does not move with the view (a
241
+ portrait of the game's interface) is recognised and ignored for a few seconds, and a safety limit prevents
242
+ any runaway turn.
243
+ - The status says what is wrong: the game's picture cannot be captured (run it borderless / windowed; on Windows
244
+ `pip install dxcam` captures more games), or the game does not receive the movements (click into it; a game
245
+ running as administrator needs Screen Magnifier as administrator too).
246
+ - Aims at the **head** (between the eyes with YuNet, eye level with Haar), not the centre of the face, and keeps
247
+ tracking it: a walking enemy's own motion is measured (its motion on screen minus the view's turn) and led. The
248
+ enemy's body is left out of the view's motion measurement.
249
+ - Enemies seen from behind are not found (the detectors find faces, not people).
250
+ - The detectors are trained on real faces: realistic characters work best, stylised or cartoon faces poorly.
251
+
252
+ ## Analysis server:
253
+
254
+ Upscaling and analysis can run on another (stronger) computer in real time:
255
+
256
+ ```bash
257
+ # On the computer that does the work (always use a token on a network):
258
+ ScreenMagnifierServer --host 0.0.0.0 --port 8765 --token SECRET
259
+ ```
260
+
261
+ The server is **pure Python - no Qt** - so it also runs on a **phone or tablet** (Android: Termux or Pydroid),
262
+ a Raspberry Pi or a headless Linux box. It needs only NumPy; optional packages add features:
263
+
264
+ | Installed | Upscaling methods | Colors | Faces | Images accepted |
265
+ |----------------------|-----------------------------------|-----------------------------------------|-------|-----------------|
266
+ | NumPy | Nearest, Bilinear, Pixel art | yes (one box per color) | - | RAWZ (lossless) |
267
+ | + SciPy | same | yes (separate regions, same as desktop) | - | RAWZ |
268
+ | + OpenCV | all, AI super-resolution included | yes | yes | RAWZ, PNG, JPEG |
269
+ | + Pillow (no OpenCV) | as above without OpenCV | as above | - | RAWZ, PNG, JPEG |
270
+
271
+ ```bash
272
+ # Android (Termux): install Python + NumPy (+ SciPy), then the package without its desktop dependencies
273
+ pkg install python python-numpy python-scipy
274
+ pip install --no-deps ScreenMagnifier
275
+ python -m ScreenMagnifier.server --host 0.0.0.0 --token SECRET
276
+ python -m ScreenMagnifier.server --selftest # checks the installation (prints "ok")
277
+ ```
278
+
279
+ The server tells the application which image formats it decodes: when it has no JPEG codec, the application
280
+ sends lossless RAWZ instead (more bandwidth, exact pixels).
281
+
282
+ Then in the *Server* tab: host, port, token -> **Connect**, and choose what to offload: upscaling of the
283
+ magnifier, upscaling of the Zoomer lens, color / face analysis. *Start local server* runs one on this
284
+ computer (for testing).
285
+
286
+ - **Never blocks the view**: at most one request per stream is in flight ("latest frame wins"); until the
287
+ server answers, the view shows its last result or a quick local scale. A slow network adds latency, never a
288
+ growing backlog.
289
+ - **Server upscaling method**: the one of the Settings tab, or any method the server offers (it may have AI
290
+ models this computer has not).
291
+ - **Image quality**: *Balanced* (JPEG 92-95, near lossless), *Fast* (JPEG 85), *Lossless* (PNG, exact
292
+ pixels for pixel inspection, more bandwidth).
293
+ - **Robust**: automatic reconnection, wrong tokens refused (no retry loop), local fallback while the server
294
+ is gone, protocol limits against malformed data (sizes, and compressed images cannot inflate beyond their
295
+ declared size).
296
+ - **Live statistics**: latency, frames per second per stream, upload / download rate.
297
+
298
+ Performance depends on the network and both computers. Measured in a single-core test machine running client,
299
+ server and display together: 85 ms latency and 9 server frames per second for a 680x512 region; separate
300
+ computers with more cores do better.
301
+
302
+ ## Key features:
303
+
304
+ - **Region selection**: full-desktop freeze overlay (all monitors), drag to select, pixel loupe with
305
+ coordinates and colour, arrow keys nudge the cursor by 1 px (Shift: 10 px), Esc / right-click cancels.
306
+ - **Follow-cursor mode**: the magnifier tracks the mouse pointer; the capture size automatically matches
307
+ what the view can show at the current zoom.
308
+ - **Adjustable magnification**: 0.25× - 32× via mouse wheel (zooms around the cursor), logarithmic
309
+ slider, presets (1×, 2×, 4×, 8×, 16×), keyboard (+ / - / 0) and double-click to fit.
310
+ - **Real-time upscaling**: only the visible crop is upscaled, straight to on-screen size (HiDPI aware):
311
+
312
+ | Method | Needs | Typical cost (200×150 → 800×600) |
313
+ |----------------------------------|----------------|----------------------------------|
314
+ | Nearest (pixel-perfect) | - | < 1 ms |
315
+ | Bilinear | - | ~2 ms |
316
+ | Bicubic, Lanczos | OpenCV | 3-6 ms |
317
+ | Pixel art (Scale2x / EPX) | NumPy | ~5 ms |
318
+ | AI super-res fast (FSRCNN-small) | opencv-contrib | ~10 ms |
319
+ | AI super-res quality (FSRCNN) | opencv-contrib | ~30 ms |
320
+
321
+ An adjustable unsharp mask (0-200 %) can be applied after smooth methods.
322
+ Missing optional libraries simply hide the methods that need them.
323
+ - **Inspection overlays**: pixel grid from 10×, hovered-pixel outline, crosshair, colour inversion,
324
+ live colour picker in the status bar (screen coordinates, hex and RGB).
325
+ - **Freeze, Save, Copy**: pause the capture to study a frame; save or copy the whole region upscaled at
326
+ the current magnification (PNG / JPEG).
327
+ - **Multi-monitor & HiDPI**: regions spanning several screens are composed; frames are physical pixels.
328
+ - **No "hall of mirrors"**: on Windows 10 2004+ the magnifier hides itself from screen capture
329
+ (`SetWindowDisplayAffinity`), so it can sit over what it magnifies. Elsewhere, capture pauses while the
330
+ cursor is over the magnifier in follow mode.
331
+ - **Binding-agnostic**: all Qt imports go through ManyQt. Tested with PyQt5 5.15 and PyQt6 6.11.
332
+
333
+ ## Download:
334
+
335
+ Ready-to-run builds for **Windows, macOS and Linux, x64 and ARM64** are attached to every
336
+ [GitHub release](../../releases) (`ScreenMagnifier-<version>-<os>-<arch>`), with `SHA256SUMS.txt`. Each archive
337
+ holds the application and the headless server (`ScreenMagnifierServer`). No Python needed.
338
+
339
+ - **Windows**: unzip, run `ScreenMagnifier.exe` (SmartScreen may warn about an unsigned app: *More info* -> *Run*).
340
+ - **macOS**: unzip, right-click `ScreenMagnifier.app` -> *Open* the first time (unsigned app), then allow *Screen
341
+ Recording* (and *Accessibility* for global hotkeys) in System Settings.
342
+ - **Linux**: `tar xzf ScreenMagnifier-*.tar.gz && ScreenMagnifier/ScreenMagnifier` (X11 / XWayland).
343
+ - The Windows ARM64 build has no OpenCV (no wheel exists): Qt upscaling and color detection work, face detection
344
+ and the OpenCV upscalers are unavailable.
345
+
346
+ ## Installation:
347
+
348
+ With **pip** (Python 3.8+) - choose the Qt binding with an extra:
349
+
350
+ ```bash
351
+ pip install "ScreenMagnifier[all]" # PyQt6 + OpenCV: every feature
352
+ pip install "ScreenMagnifier[pyqt5,opencv]" # or [pyqt5] / [pyqt6] / [pyside6], with or without OpenCV
353
+ ScreenMagnifier # start it (or: python -m ScreenMagnifier)
354
+ ScreenMagnifierServer --port 8765 # the headless analysis server
355
+ ```
356
+
357
+ | Extra | Installs |
358
+ |-------------------------------|---------------------------------------------------------------------|
359
+ | `pyqt6` / `pyqt5` / `pyside6` | the Qt binding (one is required; ManyQt runs on any of them) |
360
+ | `opencv` | OpenCV (headless): Bicubic / Lanczos / AI upscaling, face detection |
361
+ | `all` | PyQt6 + OpenCV |
362
+
363
+ - **From the repository**: `pip install ".[all]"` - or `pip install -e ".[all]"` to develop (edits apply at once),
364
+ then `pytest tests`.
365
+ - **From a release**: the GitHub release also holds the wheel:
366
+ `pip install "screenmagnifier-<version>-py3-none-any.whl[all]"`.
367
+ - **Without installing**: `pip install -r requirements.txt` plus a Qt binding, then `python -m ScreenMagnifier`
368
+ in the repository folder (each component also runs alone: `python ScreenMagnifier/upscaler/main.py`).
369
+ - With several Qt bindings installed, choose one with `QT_API`: `QT_API=pyqt6 ScreenMagnifier`. Without any, the
370
+ command says which extra to install.
371
+ - **As a library**: `from ScreenMagnifier import Upscaler, ColorDetector, MagnifierViewWidget, ZoomOverlay` (every
372
+ component is importable; each is loaded on first use).
373
+
374
+ ## Languages:
375
+
376
+ The interface speaks **12 languages**:
377
+
378
+ | | | | |
379
+ |-------------------------------|------------------------------|----------------|--------------------|
380
+ | English (`en`) | Français (`fr`) | Español (`es`) | Deutsch (`de`) |
381
+ | Italiano (`it`) | Português (Brasil) (`pt_BR`) | Русский (`ru`) | Türkçe (`tr`) |
382
+ | العربية (`ar`, right-to-left) | 日本語 (`ja`) | 한국어 (`ko`) | 简体中文 (`zh_CN`) |
383
+
384
+ By default it follows the system language (with regional fallbacks: `pt_PT` uses Português (Brasil), `zh_TW` uses
385
+ 简体中文, `de_AT` uses Deutsch). Choose another with the **🌐 language button** at the right of the status bar (the
386
+ change applies on restart, offered right away) or once from the command line: `ScreenMagnifier --lang ja`. The
387
+ common names `jp`, `cn`, `kr` and `pt` work too. Every panel fits at the default size in every language: long texts
388
+ wrap instead of being cut off.
389
+
390
+ On Linux, Japanese, Korean and Chinese need a CJK font (Windows and macOS have one):
391
+ `sudo apt install fonts-noto-cjk` (Debian / Ubuntu) or `sudo dnf install google-noto-sans-cjk-fonts` (Fedora).
392
+
393
+ Translations are plain JSON catalogs - `ScreenMagnifier/translations/<code>.json`, `{"English text": "translation"}`
394
+
395
+ - loaded by a small `QTranslator` (the `translator` component): no Qt tools needed, the same files for PyQt5, PyQt6
396
+ and PySide. Qt's own dialogs follow the language too.
397
+
398
+ **Add or update a language** (texts left empty stay in English until translated):
399
+
400
+ ```bash
401
+ python .github/packaging/translations.py --new it Italiano # start a catalog, with every text to translate
402
+ python .github/packaging/translations.py --update # after code changes: add new texts, drop old ones
403
+ python .github/packaging/translations.py --check # complete? {} placeholders and icons kept?
404
+ ```
405
+
406
+ The workflow runs `--check` on every push, and `pytest tests` checks every language through Qt.
407
+
408
+ ## Features and tabs:
409
+
410
+ | Tab | Feature |
411
+ |---------------|-----------------------------------------------------------------------------------------------------------|
412
+ | **Magnifier** | magnification, upscaling, sharpening, frame rate, overlays of the main view |
413
+ | **Zoomer** | the in-game zoom lens (target, placement, look) and its **color tools**: color code, color zones |
414
+ | **Colors** | how colors are copied everywhere: format, pick source (zoomed / original), sample size, history, contrast |
415
+ | **Detection** | what is detected: target colors, matching, faces, palette, alerts; where the zones are shown |
416
+ | **Server** | remote upscaling / analysis |
417
+ | **Shortcuts** | every keyboard shortcut of every feature, editable, with conflict detection |
418
+
419
+ ## Keyboard shortcuts:
420
+
421
+ Every shortcut is listed - and changed - in the **Shortcuts** tab: click a field, press the keys, done (window
422
+ shortcuts also have an alternate key). Conflicts are flagged live: red = the same keys twice in one scope, orange
423
+ = a window shortcut equal to a global hotkey (the global hotkey takes it). Global hotkeys are suspended while you
424
+ record one; each shows whether the system accepted it. Per-row and global reset to the defaults below.
425
+
426
+ ## Window shortcuts:
427
+
428
+ | Key | Action |
429
+ |---------------------------|------------------------------------------------------|
430
+ | Ctrl+R | Select region |
431
+ | F | Follow cursor on / off |
432
+ | Space | Freeze / resume |
433
+ | + / - / 0 | Zoom in / out / fit |
434
+ | Wheel, drag, double-click | Zoom at cursor, pan, fit |
435
+ | Ctrl+S / Ctrl+C | Save / copy the upscaled region |
436
+ | I / Esc | Eyedropper on / off (click the zoomed image to copy) |
437
+ | Ctrl+Shift+P | Screen color picker |
438
+ | C / right-click | Copy the color code under the mouse / in any format |
439
+ | T | Pin on top |
440
+ | Ctrl+, | Show / hide settings |
441
+ | Ctrl+Q | Quit (closing the window only hides it to the tray) |
442
+
443
+ ## Repository layout:
444
+
445
+ ```
446
+ ScreenMagnifier/ the repository
447
+ ├── setup.py, pyproject.toml, MANIFEST.in, requirements.txt, README.md
448
+ ├── tests/ pytest suite (pip install -e ".[all]" && pytest tests)
449
+ ├── .github/ FUNDING.yml, workflows/build-release.yml, packaging/ (release builds)
450
+ ├── docs/ icon / banner / screenshot (sources and generators)
451
+ └── ScreenMagnifier/ the package: import ScreenMagnifier
452
+ ├── __init__.py, __main__.py, main.py, mainwindow.py, server.py, ...
453
+ └── upscaler/, colordetector/, zoomoverlay/, ... one feature per subpackage, each with a demo
454
+ ```
455
+
456
+ Importing the package never changes `sys.path`; the standalone demos (`python <component>/main.py`) still work.
457
+
458
+ ## Artwork:
459
+
460
+ `docs/` holds the editable sources: `icon.svg` (48 px and larger) and `icon-small.svg` (16 - 32 px: a simplified
461
+ drawing, fine detail turns to mush at those sizes), `banner.png` (1280 x 640: also the size of GitHub's *social
462
+ preview*, set in the repository *Settings*), `screenshot.png`, and the scripts that rebuild them -
463
+ `make_icons.py` (PNG 16 - 512, Windows `.ico`, macOS `.icns` into `ScreenMagnifier/resources/`),
464
+ `make_screenshot.py` (captures the real application over an original pixel-art scene) and `make_banner.py`.
465
+
466
+ ## Contents:
467
+
468
+ Every package is standalone (no imports between sibling packages) and runnable on its own with
469
+ `python <package>/main.py`.
470
+
471
+ **Capture:**
472
+
473
+ - `regionselector/` - `RegionSelector`: frozen-desktop overlay emitting `regionSelected(QRect)`.
474
+ - `screengrabber/` - `ScreenGrabber`: timer-driven capture of a fixed region or the area around the
475
+ cursor, emitting `frameReady(QImage)`.
476
+
477
+ **Processing:**
478
+
479
+ - `upscaler/` - `Upscaler`: `process(QImage, QSize) -> QImage` with seven methods + sharpening.
480
+ `upscaler/models/` ships the FSRCNN networks (Apache-2.0, from
481
+ [Saafke/FSRCNN_Tensorflow](https://github.com/Saafke/FSRCNN_Tensorflow)).
482
+
483
+ **Advanced overlay:**
484
+
485
+ - `shortcuteditor/` - `ShortcutEditorWidget`: grouped, searchable shortcut editor (window + global scopes, alternate
486
+ keys, live conflict detection, registration status, reset), `shortcutChanged`, `recordingChanged`.
487
+ - `mousecatcher/` - `GlobalMouseCatcher`: catches (and swallows) clicks anywhere on the screen - X11 grab, Windows
488
+ low-level hook, macOS event tap - with `clicked(QPoint, int)`, `wheelTurned(int)`, `keyPressed(int)`.
489
+ - `hotkeys/` - `GlobalHotkeys`: system-wide shortcuts (Win32 `RegisterHotKey` thread, pynput elsewhere),
490
+ emitting `activated(name)`.
491
+ - `zoomoverlay/` - `ZoomOverlay`: click-through, focus-less, top-most lens fed with `setFrame()`; tells the
492
+ capture code what to grab with `sourceRect()`.
493
+
494
+ **Detection:**
495
+
496
+ - `colorswatches/` - `ColorSwatchesWidget`: grid of color swatches (history), `colorClicked(QColor)`,
497
+ right-click removal, newest first.
498
+ - `colordetector/` - `ColorDetector`: `analyze(QImage) -> dict` (regions, coverage, palette, label mask) plus
499
+ `colorInfo`, `nearestColorName`, `contrastRatio`, `wcagRating`, `maskToOverlay`, `formatColor` (13 color
500
+ code formats, `COLOR_FORMATS`) and `sampleColor` (averaged pick).
501
+ - `facedetector/` - `FaceDetector`: `detect(QImage) -> dict` with YuNet / Haar backends and the verified
502
+ on-demand model download (`downloadModel()`, `downloadProgress`, `downloadFinished`).
503
+
504
+ **Network:**
505
+
506
+ - `netprotocol/` - `FrameChannel`, `FrameServer`: dependency-free framed messages over TCP (QtNetwork),
507
+ JSON header + binary payload, size limits.
508
+
509
+ **Display:**
510
+
511
+ - `magnifierview/` - `MagnifierViewWidget`: zoom / pan view with a pluggable `processor` callable, grid,
512
+ crosshair, inversion, zoom badge, `pixelHovered` / `pixelClicked(QPoint, QColor)` and annotations (`setAnnotations()`:
513
+ boxes, labels, landmarks, privacy blur; `setOverlayImage()`: color mask).
514
+
515
+ **Application:**
516
+
517
+ - `controlpanel.py` - `ControlPanel`: settings dock bound to the view, the upscaler and the grabber.
518
+ - `advancedoverlay.py` - `AdvancedOverlayController`: hotkeys + lens + capture loop, settings persisted with QSettings.
519
+ - `advancedpanel.py` - `AdvancedOverlayPanel`: the *Zoomer* tab (target, placement, lens look).
520
+ - `analysiscontroller.py` - `AnalysisController`: rate-limited color / face analysis on a worker thread or on
521
+ the server, turned into annotations; alerts.
522
+ - `shortcuts.py` - the registry of every shortcut (scope, group, defaults) + `ShortcutStore`; `shortcutspanel.py` -
523
+ the *Shortcuts* tab. `features.py` - `FeatureSettings`: where the zones are shown (one state for every tab).
524
+ - `colorpanel.py` - `ColorPickerPanel`: the *Colors* tab (color codes, copy, history, contrast).
525
+ - `detectionpanel.py` - `DetectionPanel`: the *Detection* tab.
526
+ - `remoteclient.py` - `RemoteClient`, `RemoteProcessor`: server connection, latest-frame-wins requests,
527
+ processor plugging the server into the view / lens.
528
+ - `serverpanel.py` - `ServerPanel`: the *Server* tab.
529
+ - `analysisserver.py` / `server.py` - `AnalysisServer` and its headless entry point.
530
+ - `mainwindow.py` / `main.py` - the application window and entry point (`--tray`, `--selftest`, `--version`);
531
+ `__main__.py` - `python -m ScreenMagnifier`; `support.py` - donation links and the Qt binding check.
532
+ - `setup.py` / `pyproject.toml` / `MANIFEST.in` (repository root) - the pip package `ScreenMagnifier`; `tests/` -
533
+ pytest suite of the installed package; `.github/FUNDING.yml` - GitHub's *Sponsor* button (checked by the
534
+ workflow, which also puts its links in every release's notes).
535
+ - `.github/packaging/` - `build.py`, `ScreenMagnifier.spec`, `requirements-build.txt`: release builds (PyInstaller).
536
+
537
+ ## Integration:
538
+
539
+ ```python
540
+ from ScreenMagnifier import ScreenGrabber, Upscaler, MagnifierViewWidget
541
+
542
+ upscaler = Upscaler(method=Upscaler.Lanczos, sharpness=0.3) # type: Upscaler
543
+ view = MagnifierViewWidget(zoom=4.0, processor=upscaler.process) # type: MagnifierViewWidget
544
+ grabber = ScreenGrabber(fps=30, followCursor=True, frameReady=view.setFrame, autoStart=True) # type: ScreenGrabber
545
+ upscaler.methodChanged.connect(view.refresh)
546
+ ```
547
+
548
+ Color detection and a remote server in a few lines:
549
+
550
+ ```python
551
+ from ScreenMagnifier import ColorDetector, RemoteClient
552
+
553
+ detector = ColorDetector(targetColors=['#E01020'], tolerance=20) # type: ColorDetector
554
+ result = detector.analyze(image) # {'detections': [{'rect': [x, y, w, h], 'name': 'crimson', ...}], ...}
555
+
556
+ client = RemoteClient(host='192.168.1.20', token='SECRET') # type: RemoteClient
557
+ client.connectToServer()
558
+ view.setProcessor(client.processor('view', fallback=upscaler.process)) # Upscaled on the server.
559
+ client.upscaleReady.connect(lambda channel: view.refresh())
560
+ ```
561
+
562
+ Each option is a constructor kwarg, a `getX()` / `setX()` pair (setters are slots) and a `pyqtProperty`.
563
+
564
+ ## Platform notes:
565
+
566
+ - **Linux / Wayland**: most compositors block `QScreen.grabWindow`. Run under XWayland with
567
+ `QT_QPA_PLATFORM=xcb python main.py`.
568
+ - **macOS**: grant *Screen Recording* permission to your terminal / Python, otherwise only the wallpaper
569
+ is captured.
570
+ - **Zoomer with a very large lens at low zoom on a small screen**: if the lens overlaps the area it
571
+ magnifies in every corner and the lens cannot be hidden from capture, part of the lens may show itself;
572
+ use a smaller lens or a higher zoom.
573
+ - **Server security**: the token is a shared secret, not encryption. Keep the server on a trusted network (or behind an
574
+ SSH tunnel / VPN). By default the server only listens on this computer (127.0.0.1).
575
+ - **Windows**: the self-exclusion also hides the magnifier from your own screenshots and screen
576
+ sharing; pass `MainWindow(excludeFromCapture=False)` to disable it.
577
+
578
+ ## Support:
579
+
580
+ If ScreenMagnifier is helpful and useful to you, a star on GitHub would mean a lot and helps others discover them. If you'd
581
+ like to support development further:
582
+
583
+ <p>
584
+ <a href="https://ba9chich.com/fr/IninouUsama"><img src="https://img.shields.io/badge/ba9chich-Support%20me-E4002B?style=for-the-badge" alt="Support me on ba9chich"></a>
585
+ <a href="https://ko-fi.com/usamatn"><img src="https://img.shields.io/badge/Ko--fi-Buy%20me%20a%20coffee-FF5E5B?style=for-the-badge&logo=ko-fi&logoColor=white" alt="Buy me a coffee on Ko-fi"></a>
586
+ </p>
587
+
588
+ - **Ba9chich (Leave a tip):** [ba9chich.com/fr/IninouUsama](https://ba9chich.com/fr/IninouUsama)
589
+ - **Ko-fi (Buy me a coffee for extra energy):** [ko-fi.com/usamatn](https://ko-fi.com/usamatn)
590
+
591
+ Thank you so much <3, have a nice day :)