FAQs¶
General¶
How can I improve the detection accuracy?
How can I improve the detection accuracy?¶
The quality of detections is mainly determined by Tesseract, an open source project for OCR of printed text. NormCap builds upon this great library and can influence the quality only slightly by preprocessing the images regarding screen-specific properties. You, the user, have much more influence on the quality by paying attention to certain aspects:
1) Select the correct language¶
Make sure to select the appropriate language(s) in the settings. Selecting multiple languages might slow down the recognition.
2) Avoid selecting decorations¶
The text detection is very sensitive to elements other than text, for example borders, lines or icons. If possible, do not select those:
3) Avoid heterogeneous colors¶
If the text you want to recognize has different backgrounds, it can help to select those portions of text separately:
4) Zoom in¶
If possible, enlarge the region you want to detect, before selecting it with NormCap. This has a huge effect in situations, where zooming in doesn't decrease the quality, e.g. zooming into webpages, PDF documents or images which are not yet at their full resolution. It has little effect, if enlarging decreases the quality, e.g. for images with low resolutions.
5) Select more text¶
Sometimes Tesseract struggles with recognizing text with only very few characters, like a single word. In this case, selecting a larger portion of text can improve the accuracy.
6) Try different language models¶
The prebuilt NormCap packages are using tessdata-fast models, which offer a very good accuracy-to-speed compromise. But you can also try the slower and larger models from tessdata or tessdata-best instead.\ To find the directory in which you have to put the manually downloaded models navigate to the "Language" section of NormCap's settings, then click "add/remove" and finally "View tessdata folder in File Manager".
7) Report examples¶
If the results are still bad, please submit a screenshot of the text you are trying to recognize as an issue. Chances are small, but we might be able to improve something.
How can I start NormCap via command line interface?
How can I start NormCap via command line interface?¶
The command to run NormCap from the terminal/console depends on your operating system and installation method:
- On Windows (MSI):
%LOCALAPPDATA%\Programs\NormCap\NormCap.exe
- On macOS (DMG):
/Applications/NormCap.app/Contents/MacOS/NormCap
- On Linux (AppImage):
./NormCap-{version}-x86_64.AppImage
- On Linux (FlatPak):
flatpak run --command=normcap com.github.dynobo.normcap
- On Linux (AUR):
normcap
- Installed as Python package:
normcap
NormCap has some useful command line features. List them by appending the flag
--help
to the command mentioned above.
How can I start NormCap via a keyboard shortcut?
How can I start NormCap via a keyboard shortcut?¶
You'll have to configure that using your operating system's functionality, e.g. following these guides:
Windows¶
- Native solution: Open programs with keyboard shortcuts in Windows 10
- Tool based: Run programs via shortcut with AutoHotkey
macOS¶
Linux¶
- Ubuntu/Gnome: Set Keyboard Shortcuts
- Manjaro/Xfce, Plasma: Keyboard Shortcuts
To identify the command to run NormCap, please see the FAQ "How can I start NormCap via command line interface?"
Info
The reason for not adding an option to configure a shortcut within NormCap itself can be found in this Architecture Decision Record. If you have read the explanation and like to challenge its argumentation, feel free to open a discussion.
How can I run NormCap automatically on system start?
How can I run NormCap automatically on system start?¶
Use your operating system's functionality to autostart applications after boot. You will need the command to start NormCap and you can search for tutorials how to run that on start-up, e.g.:
- Windows: How to Add a Program to Startup in Windows 10 or 11
- macOS: How to add a startup program on a Mac
- Linux (Gnome): Automatically run program on startup
- Linux (KDE): How to automatically run program on KDE startup
Warning
Add the --background-mode
flag to the
command used to start NormCap! Then NormCap will start silently minimized to system tray without triggering a capture!
How can I start NormCap in the background?
How can I start NormCap in the background?¶
First identify the command to run NormCap on your system.
Append the flag --background-mode
to that command to start NormCap right into the
system tray, without triggering a capture.
This is e.g. useful, if, you want to autostart NormCap after system start.
How can I add additional languages to NormCap?
How can I add additional languages to NormCap?¶
The prebuilt packages are shipped with support for English only. To install additional languages, click the settings icon and in the "Languages" section of the menu click "add/remove …".
If you installed NormCap as a Python package, how to add Tesseract languages depends on your system and setup. Please search online for instructions specific to your environment.
What types of QR codes and barcodes does NormCap support?
What types of QR codes and barcodes does NormCap support?¶
NormCap uses the excellent ZXing-C++ library for code detection and decoding. This means NormCap can detect and decode all formats supported by ZXing-C++.
Why is the Windows-Installer's file size so large?
Why is the Windows-Installer's file size so large?¶
NormCap's MSI installer is much larger than the ones for Linux and macOS because the included Tesseract binaries are larger.
NormCap used to include a set of smaller binaries, which resulted in more consistent installer file sizes for all operating systems. Unfortunately, they seemed to lack some dependencies and lead to issues on some Windows systems. Hopefully, the larger binaries will fix this issue. This decision is not set in stone, so please feel free to leave some feedback regarding this topic!
Is any data send to the internet?
Is any data sent to the internet?¶
In general, NormCap works offline and does not send any data anywhere.
The only exceptions are optional features, which require accessing resources on the internet. In that case, HTTPS requests are performed and generate the typical access log data on the target server.
Those features are:
- Update check: If you enable the check for updates on start, NormCap regularly fetches its releases page from GitHub.
- Manage languages: If you download additional languages, they are being fetched from a GitHub repository.
Are there alternatives to NormCap?
Are there alternatives to NormCap?¶
Some applications offer similar features like NormCap and might be a good or even better alternative for you: It completely depends on your use case and requirements. Some similar open-source projects are:
- TextSnatcher (Linux)
- GreenShot (Windows, macOS)
- TextShot (Windows)
- gImageReader (Linux, Windows)
- Capture2Text (Windows)
- Frog (Linux)
- Textinator (macOS)
- Text-Grab (Windows)
- dpScreenOCR (Linux, Windows)
- PowerToys Text Extractor (Windows)
Troubleshooting¶
How to get debug information?
How to get debug information?¶
Launch NormCap via a terminal/console using
the right command for your system,
to which you can append the flag --verbosity debug
or short -v debug
. This will
print additional information to the console, which can be useful to identify problems.
NormCap is not starting
NormCap is not starting¶
Please try to take a look at the debug information. It might provide enough information for you to solve the issue for yourself. If it doesn't help you, don't hesitate to report your problem description together with debug information.
[Windows] Upgrading NormCap failed
[Windows] Upgrading NormCap failed¶
Did you run the msi-installer to upgrade from an older NormCap version, but the installer stated an error or the NormCap can't be started anymore?
You did nothing wrong, this is the recommended way to upgrade NormCap. But in rare cases, this does not work, because of incompatible changes in the installer between certain versions.
In that case, please try to uninstall all existing NormCap versions from your system before trying a clean installation. (In the process, your settings might get reset, and you might have to re-download languages.)
If you still experience any problems after such a clean installation, please report that issue.
[Linux] NormCap is missing screenshot permissions
[Linux] NormCap is missing screenshot permissions¶
Why is it so difficult for NormCap to take screenshots?
The Wayland protocol (successor to X Window System) requires applications to request permission for system features like taking screenshots. While this improves security, the protocol is challenging for developers to implement. The variety of Wayland servers, window managers, and versions with different implementations makes building compatible applications difficult. Most third-party screenshot tools face these same issues.
If you installed NormCap as Flatpak:
- View the permissions by running:
In the output, there should be a line like:
flatpak permission-show com.github.dynobo.normcap
screenshot screenshot com.github.dynobo.normcap [yes]
- If that is not the case, set the permission explicitly:
flatpak permission-set screenshot screenshot com.github.dynobo.normcap yes
If you're using the NormCap AppImage:
- List all applications with screenshot permissions:
Among the entries in the output, there should be something like:
dbus-send --print-reply=literal \ --session --dest=org.freedesktop.impl.portal.PermissionStore \ /org/freedesktop/impl/portal/PermissionStore \ org.freedesktop.impl.portal.PermissionStore.Lookup \ string:'screenshot' string:'screenshot'
dict entry( com.github.dynobo.normcap array [ [yes] ] )
- If that is not the case, grant permission by running:
dbus-send --print-reply=literal \ --session --dest=org.freedesktop.impl.portal.PermissionStore \ /org/freedesktop/impl/portal/PermissionStore \ org.freedesktop.impl.portal.PermissionStore.SetPermission \ string:'screenshot' boolean:true string:'screenshot' \ string:'com.github.dynobo.normcap' array:string:['yes']
Further tips for debugging:
- If starting NormCap from a terminal or shell script, ensure the calling context (e.g., the terminal application) has been granted screenshot permission.
- Run NormCap with the
-v debug
flag and look for warnings or errors in the output. - Run
dbus-monitor --session
while starting NormCap and check the (quite verbose) output for screenshot or permission-related messages.
[Linux] NormCap does not show up in system tray
[Linux] NormCap does not show up in system tray¶
Is your display environment Gnome Shell? Then you probably need to install a Gnome Shell extension to support showing applications in the top bar, e.g.:
[Linux] NormCap doesn't show a notification after capture
[Linux] NormCap doesn't show a notification after capture¶
NormCap's notifications depend on the system tray functionality. If you start NormCap, but its Icon doesn't appear in the system tray, proceed like in the question above.
[Linux] Error: Could not load the Qt platform plugin
[Linux] Error: Could not load the Qt platform plugin¶
In case you get an output like this …
$ normcap
QtFatalMsg - This application failed to start because no Qt platform plugin
could be initialized. Reinstalling the application may fix this problem.
Available platform plugins are: eglfs, linuxfb, minimal, minimalegl, offscreen,
vnc, wayland-egl, wayland, wayland-xcomposite-egl, wayland-xcomposite-glx, webgl, xcb.
… the chances are, this can be solved by installing additional dependencies:
- Arch (Wayland):
pacman -S qt6-wayland
- Arch (Xorg):
pacman -S libxcb xcb-util-cursor
- Debian/Ubuntu (Wayland):
apt install qt6-wayland
- Debian/Ubuntu (Xorg):
apt install libxcb1 libxcb-cursor0
- Fedora (Wayland):
dnf install qt6-qtwayland
- Fedora (Xorg):
dnf install libxcb xcb-util-cursor
[Linux] NormCap doesn't copy the results to clipboard when launched via shortcut
[Linux] NormCap doesn't copy the results to clipboard when launched via shortcut¶
This behavior was observed only on KDE + Wayland (#422) so far, and only when NormCap was started via a keyboard shortcut / key binding. The root cause is still unknown, if you have any information or ideas, please comment in the ticket above.
Strangely, a workaround seems to be to configure the keyboard shortcut via "System Settings" → "Shortcuts" → "Add command" and configure the command in a way, that it pipes the output to somewhere, e.g. /dev/null:
normcap 2>&1 | tee /dev/null
[Linux, AppImage] Error: AppImages require FUSE to run
[Linux, AppImage] Error: AppImages require FUSE to run¶
This is not a NormCap issue but a requirement for AppImages. You need to make sure, that
the FUSE
library is installed on your system. E.g. on Ubuntu 22.04 you need to run
sudo apt install libfuse2
.
See this blog post for details.
Please note, that the AppImage build is deprecated. Please switch to the Flatpak build via Flathub.
[macOS] When NormCap is started, an empty desktop shows up
[macOS] When NormCap is started, an empty desktop shows up¶
This issue usually occurs after installing NormCap, either for the first time or after an update.
It is a known issue related to macOS's permissions settings: If NormCap doesn't have the system's permission to take a screenshot, an empty desktop will be shown. Or to be more precise: NormCap doesn't know that it lacks permissions, tries to take a screenshot nevertheless, which results in a screenshot of the empty desktop.
Steps to solve this:
- Close NormCap, if it is running.
- Navigate to "System Preferences" → "Security & Privacy" → "Privacy" → "Screen Recording" → "Click unlock".
- Do you already see "NormCap" on the right side? If yes, "remove" [–] it. Un-ticking the checkbox is not enough!
- Click "add" [+] → "Applications" → "NormCap".
- Confirm that you see NormCap on the right side with a checkmark in front of it.
- Start NormCap, it should work now.
- You might need to repeat those steps after installing a new version of NormCap.
Hopefully, this cumbersome user experience can be improved in a future release.