@DEPRECATED please use V3.0 API

Text recognition - DEPRECATED

MyScript Cloud can recognize handwritten text and transform it into digital text.

The diagram below shows the information processed by the recognition engine to convert handwriting to text.

The recognizer will process the handwriting intelligently. It refers to lexicons, and uses a language model to understand how parts of a language come together and interact. It will not just guess one character at a time, but a whole sentence, so you can allow your application to accept complex handwriting.

URL: {"/api/myscript/v2.0/text/*"}

Making a Text recognition request - DEPRECATED

The request is made to the recognition server via POST, using the specific text recognition URL. The input is digital ink (you need to have in place your own system for capturing this ink and generating its XY coordinates). You pass the XY coordinates in the POST request.

You also need to give MyScript basic information about how your digital ink is structured and if there are any specific needs for the request. For example, do you want to see more detail in the result, or do you want to use a particular set of characters?

If you make a request without specifying any of the non-mandatory parameters, the recognizer will use a broad set of recognition resources to process it. The writing language must always be specified or it will return an error.

Structure Parameter Possible values Description Mandatory? Example
apiKey   [your application key] This is the application key provided to you on registration, and which must be included in all requests. YES apiKey=your_key
instanceId   [Instance ID get by a first request] This is an instance identification if you did a previous text recognition request NO instanceId=your_instance_ID
hwrInput hwrParameter See the content of the hwrParameter structure below. This describes the parameters to apply to the text recognition. YES hwrInput={"hwrParameter": {...}, "inputUnits": [...]}
hwrInput inputUnits See the content of the inputUnits structure below. This describes an inputUnit to send to the text recognition. YES hwrInput={"hwrParameter": {...}, "inputUnits": [...] }
inputUnits hwrInputType CHAR WORD SINGLE_LINE_TEXT MULTI_LINE_TEXT This describes the type of input, if it is a single character, a single line of text or many lines of text. NO hwrInput={"hwrParameter": {...}, "inputUnits": {"hwrInputType": "CHAR", "components": [...] }}
inputUnits components stroke string char Under “components”, specify a “type”. Usually this will be “stroke”, followed by an XY array of ink points. But it can also be “string”, followed by a string of characters, or “character” (char), followed by a single character. These types allow you to add predefined digital text to the result: That input will pass through the recognizer and be integrated into the final result. YES "inputUnits": {"components": [ "type": "stroke", "x": [], "y": [] }, { "type": "string", "string": "Today's date is " }, { "type": "char", "boundingBox": {"y": 50, "x": 50, "height": 100, "width": 100}, "character":"A" }]} OR if there are several characters: "inputUnits": { "components": [{ "type": "char", "boundingBox": {"y": 50, "x": 50, "height": 100, "width": 100}, "character":"A" }, { "type": "char", "boundingBox": {"y": 50, "x": 454, "height": 100, "width": 100}, "character":"B" }]}
hwrParameter language See the GET requests to use to obtain the list This describes the language in which the original text is written. YES "hwrParameter": { "language": "en_US" }
hwrParameter hwrInputMode ISOLATED CURSIVE VERTICAL* SUPERIMPOSED** This describes the type of writing - isolated refers to isolated characters (for example in boxed fields) and cursive is for any other type of natural writing. See the code samples for examples of use. * The recognition of characters handwritten vertically is only possible in Japanese. ** Only possible in Latin and Cyrillic languages. NO "hwrParameter": { "hwrInputMode": "CURSIVE" }
hwrParameter contentTypes See the GET requests to use to obtain the list The content type describes the expected linguistic type of input: the default is “text” which means that the recognizer will use a broad lexicon of general text. You can specify others for different types of fields such as surnames, city names, numbers, etc. You can specify more than one. NO "hwrParameter": { "contentTypes": ["text"] }
hwrParameter subsetKnowledges See the GET requests to use to obtain the list Subset knowledge is a way of telling the recognizer that you only want it to enable certain characters. For example, for a phone number field, you may want only digits to be recognized. They are language-specific but generally offer digits, punctuation, alphabetical and alphanumerical characters and upper/lower case letters. Specific sets such as Katakana, Hangul Johab etc. exist for non-Latin languages. NO "hwrParameter": { "subsetKnowledges": ["digits"] }
hwrParameter userResources See the list in the Admin UI, “My Account” tab, under the “Custom Resources” panel A user resource tells the recognizer that you want to use the given resources for recognition of the current request. NO "hwrParameter": { "userResources": ["user_resource_name"] }
hwrParameter userLkWords A list of string words A userLkWords list tells the recognizer that you want to use only the given words for recognition of the current request. NO "hwrParameter": { "userLkWords": ["word"] }
hwrParameter resultDetail TEXT, WORD, CHARACTER This describes the level of result detail you want: If you ask for TEXT level, you only get the final result for the whole ink sample. But the results can also be broken down into WORD or CHARACTER level, for example if you want to offer alternative recognition candidates. NO "hwrParameter": { "resultDetail": ["TEXT"] }
hwrParameter hwrProperties See the content of the hwrProperties structure below. This describes properties to send to the text recognition. NO "hwrParameter": { "hwrProperties": {...} }
hwrProperties textCandidateListSize A number between 1 and 20 (1=default) Sets the size of the candidate lists given at text level in the recognition result. Note: For this to be valid, make sure you ask for the corresponding level of ResultDetail. NO "hwrProperties": { "textCandidateListSize": 4 }
hwrProperties wordCandidateListSize A number between 1 and 20 (1=default) Sets the size of the candidate lists given at word level in the recognition result. Note: For this to be valid, make sure you ask for the corresponding level of ResultDetail. NO "hwrProperties": { "wordCandidateListSize": 3 }
hwrProperties characterCandidateListSize A number between 1 and 20 (1=default) Sets the size of the candidate lists given at character level in the recognition result. Note: For this to be valid, make sure you ask for the corresponding level of ResultDetail. NO "hwrProperties": { "characterCandidateListSize": 3 }
hwrProperties wordPredictionListSize A number between 1 and 20 (1=default) Sets the size of the predicted words lists given at word level in the recognition result. NO "hwrProperties": { "wordPredictionListSize": 3}
hwrProperties wordCompletionListSize A number between 1 and 20 (1=default) Sets the size of the completed words lists given at word level in the recognition result. NO "hwrProperties": { "wordCompletionListSize": 3 }

GET requests - DEPRECATED

The list of languages, subsets and content types can be fetched with a GET request. The subsets and content types that you can use are specific to each language. They respectively restrict the characters that are used by the recognizer or choose a specific lexicon, such as a list of nationalities.

To fetch the list of languages currently available:
https://cloud.myscript.com/api/v2.0//myscript/languages.json?apiKey=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

To fetch the content types for a specific language:
https://cloud.myscript.com/api/v2.0//myscript/language/[language_country_code]/contenttypes.json?apiKey=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

To fetch the character subsets for a specific language:
https://cloud.myscript.com/api/v2.0//myscript/language/[language_country_code]/subsetknowledges.json?apiKey=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

Shape recognition - DEPRECATED

MyScript Shape can recognize a fixed set of hand drawn shapes and lines.

A shape is related to one or more primitives, which is the basic geometrical unit of a shape (a line segment, an arc, etc.). Each type of shape recognized can be described by one or more of these basic primitives. For example, a rectangle is made up of 4 line segments, a circle is a type of arc, etc.

The recognizer will send you a result describing the type of shape, the primitives that constitute it and information on the shape’s orientation, size etc., so that it can be reconstituted geometrically. The resulting shape will be “beautified” to give a visually attractive geometrical shape as close as possible to the original. For example, roughly parallel lines will be made perfectly parallel, shapes that are almost touching will be connected and so on.

URL: {"/api/myscript/v2.0/shape/*"}.

Making a Shape recognition request - DEPRECATED

In the POST request, you need to send only the strokes (XY coordinates of the digital ink). No need to give additional information to the Shape recognizer, as it assumes that all input is some kind of geometrical shape or line. The result will return a shape type and various elements that allow the shape to be reconstituted (constituting lines, size, orientation, etc.). Note that the form recognition is done iteratively.

Here are the parameters needed for Shape recognition:

Structure Parameter Possible values Description Mandatory? Example
apiKey   [your application key] This is the application key provided to you on registration, and which must be included in all requests. YES apiKey=your_key
instanceId   [Instance ID get by a first request] This is an instance identification if you did a previous shape recognition request NO instanceId=your_instance_ID
shapeInput components stroke Under “components”, specify a “type”. For shapes, this will be “stroke”, followed by an XY array of ink points. YES shapeInput={"components" : [{ "type" : "stroke", "x" : [...], "y" : [...] , }
shapeInput userResources See the list in the Admin UI, “My Account” tab, under the “Custom Resources” panel A user resource tells the recognizer that you want to use the given resources for recognition of the current request. NO shapeInput={"userResources" : ["user_resource_name"]}

Analyzer recognition - DEPRECATED

MyScript Analyzer enables the recognition of mixed content by identifying the different elements composing a document. For now, only a mix of Text and Shape can be recognized, excluding music and mathematical expressions.

The Analyzer recognizer sends a result describing:

  • the text candidates (see Text recognition) with related information about positioning, orientation, justification, bounding box and font size.
  • the type of shapes (see Shape recognition), “beautified” to give a visually attractive geometrical shape as close as possible to the original.
  • the structure of the document (tables, groups, underlines) with the links between detected objects.
URL: {"/api/myscript/v2.0/analyzer/*"}.

Besides its own engine, the Analyzer recognizer uses a Text recognizer and a Shape recognizer.

The Text recognizer uses resources describing a set of recognizable text lines, and the components that determine each element. The Analyzer recognizer sends back components describing the textlines, providing their size and layout. That way, you can reconstitute textline as a font objects.

The Shape recognizer uses resources describing a set of recognizable shapes, and the components that determine each type of shape. The Analyzer recognizer sends back components in a beautified form, describing the shape’s type and which curves and line segments it uses, as well as their size and position. That way, you can reconstitute the shape as a vector object.

If required, the Analyzer recognizer can use resources that describe a set of recognizable links between objects, and the components that determine each type (groups, tables). The Analyzer recognizer sends back components describing the link types. It provides their description and references, so you can reconstitute the document layout.

Making an Analyzer recognition request - DEPRECATED

In the POST request, you need to send the strokes (XY coordinates of digital ink) some parameters (language, result type expected, etc.) to give information to the Analyzer recognizer. It assumes that all input is some kind of geometrical shape line or text line. The result will return a textline type, shape type, table type and group type with elements that allow the object to be reconstituted (constituting lines, size, orientation, etc.).

Here are the parameters needed for Analyzer recognition:

Structure Parameter Possible values Description Mandatory? Example
apiKey   [your application key] This is the application key provided to you on registration, and which must be included in all requests. YES apiKey=your_key
instanceId   [Instance ID get by a first request] This is an instance identification if you did a previous analyzer recognition request NO instanceId=your_instance_ID
analyzerInput components stroke Under “components”, specify a “type”. For shapes, this will be “stroke”, followed by an XY array of ink points. YES analyzerInput={"components" : [{ "type" : "stroke", "x" : [...], "y" : [...] , }
analyzerInput parameter parameters Under “parameter”, specify “recognition parameters”. i.e.: For text, this will be “hwrParameter”, followed by language and hwrProperties. YES "analyzerInput" : {"components" : [...] , "parameter":{ "hwrParameter":{ "resultDetail":"TEXT",<br> "hwrProperties":{}, "language":"en_US"}, "coordinateResolution":0}}
analyzerInput userResources See the list in the Admin UI, “My Account” tab, under the “Custom Resources” panel A user resource tells the recognizer that you want to use the given resources for recognition of the current request. NO analyzerInput={"userResources" : ["user_resource_name"]}

Math recognition - DEPRECATED

MyScript Math recognizes all kinds of equations and mathematical expressions. To do so, the recognizer identifies various subsets of elements that make up typical math expressions and sends a LaTeX or MathML result.

The Math recognizer uses resources to know how a math expression can be broken into various parts, laid out as fractions, using square roots, brackets, etc. and the various symbols and characters that can be found in each of those parts.

A list of limitations for Math recognition can be found in the appendix.

URL: {"/api/myscript/v2.0/equation/*"}

Making a Math recognition request - DEPRECATED

A Math recognition request is straightforward, as you only need to send the strokes (XY coordinates of digital ink) and specify whether you want the result in LaTeX or MathML format (or both), or in a symbol tree ("resultTypes" :["LATEX","MATHML", "SYMBOLTREE"]).

Here are the parameters needed for Math recognition:

Structure Parameter Possible values Description Mandatory? Example
apiKey   [your application key] This is the application key provided to you on registration, and which must be included in all requests. YES apiKey=your_key
instanceId   [Instance ID get by a first request] This is an instance identification if you did a previous math recognition request NO instanceId=your_instance_ID
equationInput resultTypes LATEX MATHML SYMBOLTREE Describes the format required for the recognition result (you can specify more than one). LATEX is default. NO equationInput={"resultTypes":["LATEX","MATHML","SYMBOLTREE"], "components":[{"type":"stroke", "x":[...], "y":[...]}]}
equationInput components stroke Under “components”, specify a “type”. For equations, this will be “stroke”, followed by an XY array of ink points. YES equationInput={"components":[{"type":"stroke", "x":[...], "y":[...]}]}
equationInput userResources See the list in the Admin UI, “My Account” tab, under the “Custom Resources” panel A user resource tells the recognizer that you want to use the given resources for recognition of the current request. NO equationInput={"userResources" : ["user_resource_name"]}
switchToChildren   boolean API migration. Childs is deprecated. You will have to use Children. NO switchToChildren=true
Some functions are deprecated in 3.0. To have your system fully updated, please change your end point prefix and replace {“/api/myscript/v2.0/”} with {“/api/v3.0/recognition/rest/”}.

Music recognition - DEPRECATED

MyScript Music recognition engine analyzes the spatial relationship between the various parts of the music document and the recognizer sends you a result in MusicXML and ScoreTREE strings.

MyScript Music requires two resource files:

  • Music Alphabet Knowledge

This is a special resource used for recognition of music elements, providing “music alphabet knowledge” to the recognizer so it is able to recognize the various elements that could possibly make up a music score.

  • Music Grammar Knowledge The way the score elements can be recognized together is specified by this grammar resource that is attached to the recognizer.

Resources are to be attached to the recognizer, in order to tell it how to perform the segmentation of all the input ink parts.

While digital ink is captured in real time, it is simultaneously recognized in the background. The Music recognizer will first analyze the spatial relationship between parts of the score. It will then use a symbol classifier that calculates the probabilities for all the elements in the suggested segmentation. Finally it will output a result.

URL: {"/api/myscript/v2.0/music/*"}

Making a Muisc recognition request - DEPRECATED

Here are the parameters needed for Music recognition:

Structure Parameter Possible values Description Mandatory? Example
apiKey   [your application key] This is the application key provided to you on registration, and which must be included in all requests. YES apiKey=your_key
instanceId   [Instance ID get by a first request] This is an instance identification if you did a previous music recognition request NO instanceId=your_instance_ID
musicInput resultTypes MUSICML SYMBOLTREE Describes the format required for the recognition result (you can specify more than one). NO musicInput={"resultTypes":["MUSICXML","SCORETREE"], "components":[{"type":"stroke", "x":[...], "y":[...]}]}
musicInput components stroke Under “components”, specify a “type”. For music, this will be “stroke”, followed by an XY array of ink points. YES musicInput={"components":[{"type":"stroke", "x":[...], "y":[...]}]}
musicInput divisions   A division refers to a type of ornamentation or variation in which each note of a melodic line is “divided” into several shorter, faster-moving notes. YES musicInput={"divisions": 480}
musicInput staff   A staff is a set of five horizontal lines and four spaces that each represent a different musical pitch. YES musicInput={'staff': {'count': staff.count,'top': staff.top,'gap': staff.gap}}
musicInput userResources See the list in the Admin UI, “My Account” tab, under the “Custom Resources” panel A user resource tells the recognizer that you want to use the given resources for recognition of the current request. NO musicInput={"userResources" : ["user_resource_name"]}

The result is returned in the requested format, ready for rendering, for example: { “instanceId”:”38dada20-0500-44b9-9c6a-d53a7b3f8c00”, “result”:{ “results”:[ {“type”:”MUSICXML”, “value”: “…”}, {“type”:”SCORETREE”,”score”:{…} ] } }