dpScreenOCR Manual

1 About dpScreenOCR

dpScreenOCR is a program to recognize text on screen. Powered by Tesseract, it supports more than 100 languages and can split independent text blocks, e.g. columns. dpScreenOCR is free and open source software that works on Windows and Unix-like systems with X11.

2 Installation

2.1 Installing dpScreenOCR

2.1.1 Windows

The dpScreenOCR website provides an installer and a ZIP archive. The latter doesn’t need installation: unpack it anywhere you want and run dpscreenocr.exe.

2.1.2 Unix-like systems

The dpScreenOCR website provides several download options, including repositories and packages for Debian, Ubuntu, and derivative systems. Downloads for other systems may be added later.

If you don’t find a suitable choice for your system, download the source code tarball, unpack it anywhere, and follow the instructions in the doc/building-unix.txt file.

2.2 Installing languages

2.2.1 Windows

dpScreenOCR for Windows is shipped with the English language pack. To install other languages, visit the Languages page, download .traineddata files you want, and place them in the tessdata directory located in the same folder as the dpScreenOCR executable.

You can also download languages from other places, but make sure they are intended for Tesseract 4. An attempt to use data designed for another Tesseract version will cause dpScreenOCR to crash.

2.2.2 Unix-like systems

Use your package manager to install language packs for Tesseract. The package names may vary slightly across systems, but they usually start with “tesseract” and end with a language code or name. For example, the package for German have the following names:

Be aware that on some systems (like Fedora) English is a part of the main tesseract package.

There are also two special packs that provide extra features rather than languages: osd (automatic script and orientation detection) and equ (math and equation detection). dpScreenOCR doesn’t use them.

3 Usage

3.1 Overview

dpScreenOCR is simple to use:

  1. Choose some languages in the Main tab.
  2. Move the mouse pointer near the screen area containing text and press the hotkey shown in the Main tab to start the selection.
  3. Move the mouse so that the selection covers the text and press the hotkey again.

After these steps, dpScreenOCR will recognize the text from the selected area and process it according to the actions from the Actions tab.

3.2 Main tab

3.2.1 Status

The status shows the state of dpScreenOCR:

The yellow and red status messages are also displayed in the title of the dpScreenOCR’s window.

3.2.2 Character recognition

Options in this section control how dpScreenOCR will recognize text.

3.2.2.1 Split text blocks

If this option is enabled, dpScreenOCR will try to detect and split independent text blocks, e.g. columns. This behavior is best described by the following picture:

3.2.2.2 Languages

The language list shows all available language packs that dpScreenOCR can use to recognize text. You can choose more than one language, but be aware that this may slow down recognition and reduce its accuracy.

If you want to install more language packs, read the “Installing languages” section.

3.2.3 Hotkey

The hotkey is used to start and end the on-screen selection. The default is Control + Grave accent. To cancel the selection, press Escape.

The hotkey is global: it works even if dpScreenOCR’s window is minimized. If pressing the hotkey has no effect, it probably means that another program is already using it. In this case, try to choose a different key combination.

3.3 Actions tab

The Actions tab allows you to choose what dpScreenOCR will do with the recognized text.

3.3.1 Copy text to clipboard

This action will copy the text to the clipboard.

3.3.2 Add text to history

This action will add the text to the history located in the History tab. You can later save the history to a file in plain text, HTML, or JSON format.

3.3.3 Run executable

This action will run an executable with the recognized text as the first argument. The “Run executable” entry expects either an absolute path to the executable, or just its name in case it’s located in one of the paths of your PATH environment variable.

3.3.3.1 Using dpScreenOCR with GoldenDict

Point “Run executable” to the path of the GoldenDict’s executable (or just its name on Unix-like platforms) and make sure GoldenDict is running. This way GoldenDict will receive the text from dpScreenOCR and show it in a pop-up window.

3.3.3.2 Running scripts on Windows

3.3.3.2.1 Batch files

dpScreenOCR doesn’t run batch files (“.bat” or “.cmd”) for security reasons. Please use Python or any other scripting language instead.

3.3.3.2.2 Creating file associations

Before using a script, make sure that the file association is configured correctly so that you can launch the script just by its file name, without mentioning the interpreter explicitly. The simplest way to test this is to type the name of the script with some command-line arguments in cmd.exe. If the script runs and receives all arguments, you can skip this section.

We will use Python as an example, but for other languages the process is similar. Open cmd.exe as administrator and run:

C:\>assoc .py

If the script still receives only one argument (path to the script), this means that Windows actually use a different association for the given extension and ignores the one set with assoc/ftype. To fix that, open regedit and make sure the values of the following keys end with %*:

HKEY_CLASSES_ROOT\Applications\python.exe\shell\open\command
HKEY_CLASSES_ROOT\py_auto_file\shell\open\command

A special tip for Python users: note that in the examples above the association uses Python Launcher (py.exe) rather than a concrete Python executable (python.exe). This allows using Unix-style shebang lines to select the Python version on per-script basis. For more information, read Using Python on Windows.

3.3.3.2.3 Hiding console window

Almost all scripting language interpreters for Windows are shipped with a special version of the executable that doesn’t show the console window. For example, it’s pythonw.exe for Python and wperl.exe for Perl.

A special file association is usually added during installation, so you can hide the console window by simply changing the extension of the script. For example, Python scripts with .pyw extension are associated with pythonw.exe instead of python.exe. Other languages have their own conventions, like .wpl for Perl (wperl.exe), .rbw for Ruby (rubyw.exe), .wlua for Lua (wlua.exe), etc. If such an association does not exist, you can create it manually as described in the previous section.

3.3.3.3 Running scripts on Unix-like systems

Before using your script, make sure it starts with a proper shebang and you have execute permission (run chmod u+x your_script...).

Here is an example Unix shell script that translates the recognized text to your native language using Translate Shell, appends both original and translation to the translations.txt file in your home directory, and displays the translation as a desktop notification.

#!/bin/sh

TR=$(trans -b "$1")

printf "> Original\n\n%s\n" "$1" >> ~/translations.txt
printf "> Translated\n\n%s\n\n\n" "$TR" >> ~/translations.txt

notify-send "Translation" "$TR"

3.4 History tab

The History tab shows the history of recognized texts. A text is only added here if the corresponding action is enabled in the Actions tab. Every text in the list has a timestamp taken at the moment you finish the selection.

You can save the history to a file in plain text, HTML, or JSON format.

4 Tweaking

This section is intended for advanced users and developers. It describes how to change some settings that are not available in the dpScreenOCR’s interface.

dpScreenOCR saves settings in the settings.cfg file. Depending on the platform, you can find it in the following directories:

You can modify the file with any text editor. To reset an option to the default value, remove it from the file; to reset all options, clear the file or delete it. Be aware that dpScreenOCR rewrites settings on exit, so make sure you close the program before making changes.

An option value can be one of the following types:

Here is the list of all options that can only be changed by editing the settings file:

5 Troubleshooting

This section contains the list of common issues and solutions to them. If the solutions don’t help, or you have an issue that is not listed here, please report the problem on the issue tracker.