Custom recognition
MyScript’s recognition technology is very flexible. While the default configurations support common use cases, this page explains how you can fine tune them to address specific needs.
Why customize the recognition?
MyScript Developer Portal lets you download recognition assets to support a wide range of languages, as well as math and diagram use cases. Each pack comes with a ready-to-use configuration that will work in most cases.
However, there are a few situations where you may want to adapt these provided configurations:
- You need the engine to recognize some vocabulary that is not included within the default MyScript lexicons, like proper names. In this case, you may build and attach a custom lexicon.
- You target different education levels with a math application and want to restrict the amount of symbols that MyScript can recognize: this will reduce some possible ambiguities (many math symbols are very similar) and improve the overall user experience. In that case, you can build and attach a custom math grammar.
-
You are building a form application and want to reduce some fields to only accept certain types of symbols, such as alphanumerical symbols, digits or even capital letters. In this case, consider building and attaching a subset knowledge.
- You need more or less recognition candidates to be made available to the end user, or you plan to index the recognition results for search purposes and want to just consider the top n candidates. You may edit the configuration accordingly.
Recognition resources
Resources are pieces of knowledge that can be attached to the recognition engine to make it able to recognize a given language or content.
Alphabet knowledge
An Alphabet knowledge (AK) is a resource that enables the engine to recognize individual characters for a given language and a given writing style. Default configurations include a cursive AK for each supported language.
Linguistic knowledge
A Linguistic knowledge (LK) is a resource that provides the engine with linguistic information for a given language. It allows the recognition engine to improve its accuracy by favoring words from its lexicon that are the most likely to occur. Default configurations include an LK for each supported language.
An LK is not mandatory but not attaching one often results in a significant accuracy drop. It may be relevant if you do not expect to write full meaningful words, for instance if you plan to filter a list with a few letters.
Lexicon
A lexicon is a resource that lists words that can be recognized in addition to what is included into linguistic knowledge resources.
You can build and attach your own custom lexicons.
Subset knowledge
A subset knowledge (SK) is a resource that restricts the number of text characters that the engine shall attempt to recognize. It thus corresponds to a restriction of an AK resource. It can be useful in a form application, for example, to restrict the authorized characters of an email field to alphanumerical characters, @ and a few allowed punctuation signs.
You can build and attach your own custom subset knowledge.
Math grammar
A math grammar is a resource that restricts the number of math symbols and rules that the engine shall be able to process. In education use cases, it can prove very useful to adapt the recognition to a given math level (for instance, only digits and basic operators for pupils).
You can build and attach your own custom math grammars.
Configuration files
Role
As explained in the runtime part of the guide, iink SDK consumes configuration files, a standardized way to provide the right parameters and knowledge to recognize a specific type of content.
Deployment and usage
To deploy and use a configuration, you need to:
- Deploy the
*.conf
file with your application, along with all the resource files that it references (make sure that all paths are correct). - Add the folder containing the
*.conf
file to the paths stored in the engine configuration for theconfiguration-manager.search-path
key. - Depending on the content type, set the right configuration keys. For instance, to recognize text (in “Text”, “Diagram” and “Text Document” parts)
you will need to ensure that the values of the
text.configuration.bundle
andtext.configuration.name
keys are matching your text configuration bundle and configuration item name (see example below).
Syntax
A configuration file is a text file with a *.conf
extension. It is composed of a header (identifying a configuration bundle) and one or more named
configuration items (defining configuration names) separated by empty lines.
Here is an example:
# Bundle header
Bundle-Version: 2.0
Bundle-Name: en_US
Configuration-Script:
AddResDir ../resources/
# Configuration item #1
Name: text
Type: Text
Configuration-Script:
AddResource en_US/en_US-ak-cur.res
AddResource en_US/en_US-lk-text.res
SetTextListSize 1
SetWordListSize 5
SetCharListSize 1
# Configuration item #2
Name: text-no-candidate
Type: Text
Configuration-Script:
AddResource en_US/en_US-ak-cur.res
AddResource en_US/en_US-lk-text.res
SetTextListSize 1
SetWordListSize 1
SetCharListSize 1
Explanations:
- Lines starting with
#
and!
are considered as comments and ignored. - Lines starting with a space are continuation lines. Here, several commands are gathered under
Configuration-Script
. - The value provided as
Bundle-name
is the name of the bundle. This is what iink SDK expects as a possible value for thetext.configuration.bundle
configuration key. In this example, it would been_US
. - The value provided as
Name
defines a configuration item. This is one of these names that iink SDK expects as a possible value for thetext.configuration.name
configuration key. In this example, it could betext
andtext-no-candidate
. A given engine can only be configured with a single configuration item for each type of recognizer at any point in time. - Possible values for the
Type
key are:Text
,Math
,Shape
andAnalyzer
. They correspond to the types of content that the core MyScript technology is able to recognize.
The following tables lists the types of configuration items that you need to provide for iink SDK to support its different content types:
Content type | Required configuration item types |
---|---|
Text |
Text |
Math |
Math |
Diagram |
Text + Shape + Analyzer
|
Drawing |
None |
Text Document |
Text + Math + Shape + Analyzer
|
Raw Content |
Text 1 + Shape 2 + Analyzer
|
Configuration commands
The table below lists some possible configuration commands (to be placed under Configuration-Script
):
Configuration item type | Syntax | Argument |
---|---|---|
All | AddResDir DIRECTORY |
Folder that the engine shall consider for resource files relative paths |
 | AddResource FILE |
Name of an individual resource file to attach |
Text | SetCharListSize N |
An integer between 1 and 20, representing the number of character candidates to keep |
 | SetWordListSize N |
An integer between 1 and 20, representing the number of word candidates to keep |
 | SetTextListSize N |
An integer between 1 and 20, representing the number of text candidates to keep |
-
If you enable text recognition on raw content (see configuration) ↩
-
If you enable shape recognition on raw content (see configuration) ↩
Attaching resources
Resouces are attached in the Configuration-Script
part of the configuration items by using the AddResource
command.
For example, in the case of an en_US
AK, you would write:
AddResource en_US/en_US-ak-cur.res