Updated: November 26, 2003
Please contact Vividata support for archived copies of OCR Shop XTR/API documentation from previous releases.
The OCR Shop XTR™/API Software Developer's Kit is the latest in Vividata's series of character recognition and image processing products. The OCR Shop XTR™/API provides unsurpassed recognition accuracy for Sun Solaris™ and Linux™ production environments and for developers looking to embed powerful OCR functionality into custom applications. Vividata™ has applied its dozen years of experience in document imaging, character recognition, and Unix technology, to combine the ScanSoft® SDK Version 5.0 with Vividata™'s extensive image-processing technologies to develop the OCR Shop XTR™/API. Further, with options to output PDF and HTML documents that combine recognized text with embedded images, OCR Shop XTR™/API provides the flexibility, accuracy and power to meet the production needs of high-end custom development requirements.
In this documentation, "you" refers to the application developer and "development seat" refers to the application developer's machine, where the OCR Shop XTR™/API is installed. The "end user" refers to the application end user and the "target system" refers to the application end user's machine.
OCR is the process of transferring text from printed pages into a computer file on screen that can be edited without retyping. It is the process of translating bitmap image data into editable text. Text characters are designed by assigning a code corresponding to each key on the keyboard, be it a letter, number or symbol. There are a variety of different code sets in use, but the most common code set is the ASCII (American Standard Code for Information Interchange) table of character equivalents.
The recognition engine is based on the ScanSoft® SDK 5.0
Note: All features are included with and are functional in the development seat. However, for end user run-time licenses, some features and input/output formats are supported as add-on options and are not licensed in a basic run-time license key. Please contact Vividata™ LLC Sales and Support at (510) 658-6587 Ext. 107 for pricing information and details.
Supported input formats:
Text recognition uses a character set and one or more languages. English is the default language and all available languages are included with the development seat. For run-time licenses, additional languages are available as add-on language packs. Multiple languages may be specified for a single document, as long as they use the same character set.
Supported output text document formats:
Supported output subimage (graphical) formats:
To install the API:
LD_LIBRARY_PATHis set. Normally this environment variable is set to at least
|All files in the API distribution|
|Libraries, resource files|
|Source code for a sample program|
|Ghostscript resource files|
In addition, symbolic links are created in /usr/local/include/ and /usr/local/lib/ to the include files and libraries in /opt/Vividata/.
The default location for the development seat installation is /opt/Vividata/. If you decide to install the Vividata™ development seat elsewhere, you must set the environment variable
VV_HOME before running the installer, installing the run-time license key, or using the OCR Shop XTR™/API functionality.
You can set the temporary directory used during installation and use of the OCR Shop XTR™/API by setting the environment variable
TMP_DIR to a specific directory.
/tmp is used by default.
You must install the run-time license key for testing included with your development seat before you can run a sample program. Please see the subsection Development Seat Licensing.
Please see the section on Basics of Usage for information on running the included sample program and using the API.
To uninstall the API development seat, remove
/opt/Vividata, as well as the symbolic links in
and the symbolic links in
The main daemon process permits the creation of multiple instances of the OCR engine, serving one or more client programs. Furthermore, the API is designed in such a way that the OCR engine code is isolated from your application to increase process stability and to reduce dependencies, such that the OCR engine and your application do not share namespace, and a crash in your application will not affect the OCR engine.
In order for the OCR engine to function, you must set up the licensing and resource files properly on the end user's target system.
Please see the section Licensing for information on how licensing works in general and specifically how to obtain and install purchased run-time licenses for an end user's target system.
You may install the resource files yourself in the process of installing your application, or we can provide a redistributable installer. The redistributable installer is similar to the development seat installer, but it installs only the appropriate resource files for a target machine. Please contact us for information on obtaining and using a redistributable installer.
The default location on the target system for the run-time resource files is
/opt/Vividata/. If you decide to install the Vividata resource files elsewhere, you must set the environment variable
VV_HOME before running the installer, installing the run-time license key, or using the OCR Shop XTR™/API functionality. This ensures that the OCR Shop XTR™/API code can find the resource files and license key file.
Note: You are not permitted to redistribute the OCR Shop XTR™/API libraries or include files.
The license key file will be installed here.
Development seat licensing is regulated by the terms of the Vividata Developer License Agreement unless superceded by a previously executed contractual agreement.
How to obtain the run-time license key for testing which comes with your development seat:
A run-time license key with all features permitted will be emailed to you in conjunction with the development seat distribution.
How to install the development seat run-time license key for testing:
The license key comes encapuslated in a shell script. After installing the development seat distribution, you must install the run-time license key by running the shell script as root with the command:
This will place your license key in the file
If you are using a directory other than the default
/opt/Vividata/ for the development seat installation directory, you must set the environment variable
VV_HOME to the correct directory before installing the license key.
A run-time license is checked out at the first occurrence of one of these events:
vvEngAPI::vvReadImageData(const struct vvxtrImage * img))
A run-time license is checked in when any one of these events occurs:
A run-time license key is bound to the machine id (hostid on Solaris, or MAC addres on Linux) of the end user's target machine and controls these features:
The run-time license key should be installed on the target machine at the same time as your application. Under normal operating conditions, all licensing will work successfully if the license key file is in place when the application runs.
Please see the sections Run-Time Usage and How to Install a Run-Time License Key.
If you prefer, or if you have not already purchased run-time licenses and would like to do so, we are able to provide run-time licenses directly. Please email support by filling out the web form at http://www.vividata.com/support_contact.html
/opt/Vividata/for Vividata™'s resource files and license key, you must set the environment variable
VV_HOMEto the correct directory.
/opt/Vividata/config/vvlicense.dat, or another directory as specified by
vvlmstopdoes not seem to work, you can kill the license process by hand. On Linux, the process should be named "vvlicense" and on Solaris, it will be named "ocrxtrdaemon".
/opt/Vividata/, you must set the environment variable
VV_HOMEto the correct Vividata installation directory.
/opt/Vividata/config/vvlicense.datto see the license key string itself.
/opt/Vividata/bin/vvlmstatus -k <keystring>
or by looking up the license key on our website:
Your application must include these headers:
Additional headers are included with the OCR Shop XTR™/API distribution for your reference and use.
Your application must link with these libraries:
libsocket.a(for Solaris only)
libposix4.a(for Solaris only)
The first four of these libraries are included with the API distribution and are placed on your development seat system as part of the installation process; the other libraries you should already have as part of your operating system or as part of gcc.
The OCR Shop XTR™/API libraries are compiled with gcc 3.3, and we highly recommend using this compiler when linking with our libraries. Please let us know if you need to use a different compiler or encounter any problems.
Before you can run the sample program or your own application, the daemon must be started. To start the daemon, run the command:
A sample program is included with the OCR Shop XTR™/API distribution. To compile the sample program:
You can run the sample program with the command:
It will prompt you for information to run a test document through the engine. We have included a sample input file:
The daemon may be instructed to print out log information by setting the environment variable
VV_DEBUG prior to starting the daemon. (See the include file
vvLog.h for appropriate values for
VV_DEBUG.) Similarily, your application can print out verbose log information; please see the call to
vvxtrSample.cc and the FAQ question How do I generate log output?.
When you begin code development, we recommend you use the sample program
vvxtrSample.cc, the header
vvxtrAPI.h, and the webpages at http://www.vividata.com/xtrapi as your primary sources for documentation and information on the use of the API. The Frequently Asked Questions also provides valuable information. Please contact us for any additional questions.
The API features:
Major updates in this release include:
We plan future improvements to be included in subsequent releases, including:
Vividata's website: http://www.vividata.com
Documentation Copyright © 2003-2014, Vividata™. All Rights Reserved.