# Create Models

## Model

A model in Blue Locate and Blue Read is a group of features that appears following a certain pattern. This pattern can be geometrical position (Node Model) or the number of character features that appear glued to each other (String Model in Blue Read). For example, a node model can be a group of 5 features, which form a star formation in terms of their relative geometrical positions. Models are just like labels, so you can consider them a "group label." By creating a model, you define a label consisting of multiple features that appear following a specific pattern in views. Like individual feature labels, the model should be defined and created (labeled) on each view. But the model in Blue Locate and Blue Read is not a neural network and it is not trainable. The model can/cannot be correctly found on each view after processing, and so there can be matched/mismatched models in views.

In instances where the characters in your image are organized into regular, consistent groups, defining a model will improve performance. There are three types of models that you can define in Blue Read:

- Node Model
- String Model
- Regex Model

To create a model, from the Tool menu, select Edit Models, which will launch the Model Editor dialog. Select the type of model to create.

Note:

- If you have defined one or more models, the tool will use the model information to improve its performance by attempting to fit found characters to the models that you have defined, using the model with the best score.
- In terms of performance, the Regex model is generally the fastest to execute, while the Node model is typically the slowest.

## Blue Read Node Model

You can create node models that describe the spatial relationship between a group of characters, and also which character values (a digit or an uppercase letter) are legal for each node in the model. The node model is for use with strings that should contain the same number of characters in each image. They are also useful in situations where the characters are situated along an arc, for example.

### How to Create a Node Model

To use a node model, do the following:

1. After adding the tool, configuring the ROI (Define Region of Interest (ROI)) and setting the character Feature Size (Sampling Parameters), process the tool (press the Book icon).

2. Select all of the yellow found characters you want to include in the node model (shift-click or shift-drag to draw a box), then right-click over a selected character and select Create Model.

   Note: If you select Create Model with nothing selected, then the model will be created from all of the features found in the image.

3. Define your node model within the Model Editor dialog.

4. For each node within the model, you can refine the characteristics of the node, such as specifying if it should be a numeric digit or an uppercase letter character (the default is that the node can be any type of character).

   To specify characteristics of a node, select the node, which will open the Node settings for the selected instance.

5. Close the dialog by pressing the X button in the top-right corner of the dialog.
6. The model will then be applied to the view that was open when the Model Editor was launched.
7. Process the tool (press the Book icon) to apply the model to the rest of the views.
8. Review the results.

### Node Model Editor

Optimize

Parameter | Description
--- | ---
Optimize | The Optimize option uses the results (markings) of the last run of the tool and optimizes the geometry and fielding of the nodes in the model (you can select which to use with the checkboxes) based on the markings. Generally, when you create a node model, you specify the geometry from the nodes found in one image. The Optimize option lets you adjust the node positions based on a several images.
Enable | Specifies whether or not the model should be active.
Threshold | Specifies the lowest score allowed to be a match for the model.
View Filter | Specifies a filter to determine which views the model will be applied to. When used, the model will be selectively enabled for views that satisfy the filter.
Occurrences | Specifies how many instances of a model should be detected. Enable the all checkbox, and the tool will detect all model instances.
Search Space
Constrain | When enabled, the Constrain checkbox limits model matches to the Range specified for the Degree of Freedom (DOF) parameter. If disabled, models will be matched regardless of the Range specified for the DOF parameter, and the Range values will be grayed out to indicate that they are not active.
Angle | Specifies the possible orientations the model may exhibit.
Scale | Specifies the amount of deviation in the overall model size, and in the deviation of inter-node spacing, that will be allowed for a match. For example, a value of [0.8, 1.2] would specify that the overall size of the model must be between 80% and 120% of the nominal size, and the spacing between any two nodes in the model must also be between 80% and 120% of the nominal spacing.
Aspect-Ratio | Specifies the amount of deviation in the overall model aspect ratio, and in the deviation of inter-node ratios, that will be allowed for a match.
Shear | Specifies the amount of deviation in the shear mapping of the model, and in the deviation of inter-node shearing, that will be allowed for a match.
X | The X and Y parameters specify the search region within the View, expressed in percentage terms. For example, to search only the upper-left quadrant of a View, you would specify [0%, 50%] for both X and Y. With these settings, only model matches where all of the nodes lie within the specified region will be returned. In the example shown below, A is matched, but B is outside of the X and Y range, so it is not matched with A to form the A-B model.
Y
Node
Position | Specifies the expected pixel position of the selected node.
* (Character Type) | Specifies the type of character that should be matched at the selected node.
Oriented | Specifies whether this node is oriented or not. If this parameter is enabled, the Angle parameter is activated below and only the character feature with this specific angle will be matched for the selected node.
Angle | Specifies the orientation of this node in degrees. This parameter is only activated when the Orientation parameter is enabled.
Size | Specifies the size of this node.
Threshold | Specifies the minimum feature score that should be matched for the selected node.

Note: The Oriented, Size, and Threshold parameters are exposed only in Expert Mode.
Note: The Angle parameter is exposed only when the Oriented parameter is enabled.

## Blue Read String Model

The string model is the simplest model to use and define; you simply define the minimum number of characters you expect to find, along with the angular variation of the characters from the horizontal boundary of the ROI that you expect to encounter in your images.

### How to Create a String Model

To use a string model, do the following:

1. After adding the tool, configuring the ROI (Define Region of Interest (ROI)) and setting the character Feature Size (Sampling Parameters), process the tool (press the Book icon).

2. To create your string model, from the Tool menu, select Edit Models, and from the Model Editor dialog, select String Model.

3. Enter the number of characters the string should contain in the Minimum Length field.
4. The tool will return the specified number of characters that are present in the ROI. The matched characters must lie along a single horizontal line, which is defined by using the Angle parameter, and is the allowable deviation from the horizontal axis of the ROI.
5. Close the dialog by pressing the X button in the top-right corner of the dialog.
6. The model will then be applied to the view that was open when the Model Editor was launched.
7. Process the tool (press the Book icon) to apply the model to the rest of the views.
8. Review the results.

## Blue Read Regex Model

Regex models provide a flexible control for defining the exact format of the strings that you are interested in by allowing you to define the characters you want to find via a regular expression.

### How to Create a Regex Model

To use a regex model, do the following:

1. After adding the tool, configuring the ROI (Define Region of Interest (ROI)) and setting the character Feature Size (Sampling Parameters), process the tool (press the Book icon).

2. To create your regex model, from the Tool menu, select Edit Models, and from the Model Editor dialog, select Regex Model.

3. Define your regular expression in the Regex field.

   Note:
   - When constructing your regular expression, the simplest wildcard is the period; it means "match any single character." You can then use modifiers after characters or wildcards to specify how many characters to match.
   - The minimum match length for the regex model is three characters (not including the space character) or longer.
4. The regex model will return the characters that match your regular expression within the ROI. The matched characters must lie along a single horizontal line, which is defined by using the Angle parameter, and is the allowable deviation from the horizontal axis of the ROI.
5. Close the dialog by pressing the X button in the top-right corner of the dialog.
6. The model will then be applied to the view that was open when the Model Editor was launched.
7. Process the tool (press the Book icon) to apply the model to the rest of the views.
8. Review the results.

### Regex Model Syntax

The regex model uses the following syntax:

Code | Definition
--- | ---
. | Matches any character, except for space.
[A-Za-z] | Matches any English character. See "Character classes" below.
[^A-Z] | Matches any character, except for space and the upper case characters.
\d, \u | Equivalent to [0-9] and [A-Z] respectively.
jan|feb | Matches either "jan" or "feb"
() | Groups characters. Useful if followed by ?, *, +, or {5}, or to delimit the range of or an either/or expression using |.
space | Space is special. It does not match any feature, but tells the Blue Read tool's model matcher to expect a longer gap between features here, which affects the scoring.
\*, \?, \+, \(, \), \[, \], \{, \}, \., \|, \\ | Escapes a literal control character.
? | The preceding expression is optional.
* | The preceding expression repeats 0 or more times.
+ | The preceding expression repeats 1 or more times.
{5} | The preceding expression repeats exactly 5 times.
{5,8} | The preceding expression repeats 5 to 8 times, inclusive.
Other character | Matches that character literally.

Inside of character classes (for example [a-z]) the following syntax rules apply:

- A - denotes a range, unless it occurs at the beginning of the class specification (possibly after ^) or at the end. If you need a literal -, place it in one of those locations.
- A closing square bracket ] ends the class, unless it is escaped with \, or it occurs at the very beginning of the class specification (possibly after ^).

- If you want a backslash, you should escape it with another backslash.

  Note: The only characters with special meaning are ], -, and \. Any other character (for example *, ?, ), |, etc) have their literal meanings, and should not be escaped.

### Space in a Regex String

You use space (blank) characters in the regex string to indicate expected gaps between characters. If you specify a large gap the tool may skip over characters during matching. A general guideline is to use a space character to indicate a gap that is as large as the feature size you've specified.

As described in the Regex Model Syntax topic, a (normal ASCII) space character is special. It does not match a feature, but tells the model matcher to expect a bigger gap between features at that position. You can add several spaces if wider gaps are expected. The final "match string" for the model will include those spaces.

Space is the only character that is special. Other whitespace characters simply try to match a feature which is labeled with that particular character.

Note: The regex model does not support any "multi-line" models. CR or LF characters have no special meaning.

### Unicode Character Matching for Regex Model

The regex model supports matching Unicode characters, with the caveat that it operates in units of Unicode code points – each feature is assumed to correspond to a Unicode code point.

Note: In Unicode, there are so-called "combining characters", which means that a character can consist of several code points. This is a common way to express unusual combinations of diacritics.

Unicode provides so-called precomposed characters – characters (even with diacritics) which only consist of a single code point. To ensure that these are used, the user should use the Unicode normalization form NFC. (Notable exceptions are half-width Japanese kana with dakuten or handakuten diacritics – these have no precomposed form in Unicode.)

### Regex Models and Empty Features

When labeling characters for training, after a labeled feature has been added, but before it has been given a character, it exists in a special "empty" state. As a special case, the regex model will always be able to match empty features, regardless of the character class or literal character used. This helps with work flows where you are using the model to be able to enter the ground truth for many features as one string.

## Working with Models

If you have defined one or more models in your Blue Read tool, then labeling images is simplified and accelerated in some important ways.

- When you start to label an image that has no found features, as soon as you have labeled a few characters the tool will suggest a likely Model location, including the locations of all the features in the Model:

  Once the Model has appeared, you can simply type the correct character values into the text field and the tool will automatically create all of the labels:

  After specifying the character values, you also need to adjust the feature positions so they are correct:

- When you are starting from an image with found features, the process is even simpler. Simply right-click and select Accept View:

  In this case, only the features that were matched by the Model or Models are converted to labels:

## Import/Export Model

Like Blue Locate, Blue Read models also support being exported and imported into other Blue Read tools. This allows you to quickly create new models, based on an existing model by importing a previously created model.

When exporting a model, VisionPro Deep Learning will package all of the information about the model into a model archive file. Then, when importing a model archive file into another Blue Read tool, a duplicate of the model is created. See Import/Export Model